BLUX-cA – Clarity Agent
Conscious, Constitutional, Multi-Model, and Fully Audited
BLUX-cA is the Conscious Agent kernel of the BLUX ecosystem — a constitution-driven, multi-agent reasoning engine designed to provide aligned guidance, orchestrated tooling, secure code execution, self-reflection, and verifiable intelligence.
It is the center of gravity for BLUX-Lite (orchestrator), BLUX-Quantum (CLI operations), BLUX-Guard (security cockpit), the Doctrine (ethical spine), and your future daughter-safe autonomy model.
🧠 Adapter Training Loop
The end-to-end adapter training, validation, and evaluation workflow lives in train/README.md. The BLUX-cA dataset is a separate repository and must be provided via DATASET_DIR (for example /workspace/blux-ca-dataset).
- Doctrine contract: see
docs/DOCTRINE_INTEGRATION.md. - Training/eval mix and gates: see
docs/TRAINING_POLICY.md. - Canonical doctrine text lives in the BLUX Doctrine repository.
Run evaluation probes
python ca.py eval --dataset-dir /workspace/blux-ca-dataset --suite doctrine
python ca.py eval --dataset-dir /workspace/blux-ca-dataset --suite all
Reports are written to runs/eval_<timestamp>.md with PASS/FAIL per probe and doctrine boundaries.
🌟 Philosophy
BLUX-cA operates on three foundational principles:
- Light > Denial – Confronting reality with compassion
- Integrity > Approval – Truth-aligned responses over convenience
- Truth > Comfort – Honest guidance that serves growth
All while keeping data local, audit trails immutable, and user sovereignty non-negotiable.
⚡ Core Capabilities
1. Adaptive Memory & Constitutional Learning
A privacy-first, consent-only memory system featuring:
- Weighted Reinforcement Memory – Learns from interaction patterns
- Memory Decay – Outdated information naturally fades
- Consent-Gated Persistence – User control over data retention
- Router-Bound Context Assembly – Intelligent context management
- Reflective Distillation – Summaries and filtered insights
- Hash-Chained Audit Logs – Append-only, tamper-evident records
Memory lives locally on the user's device — never externally.
2. The Conscious Heart
blux_ca.core.heart.ConsciousHeart orchestrates the core reasoning loop:
Processing Pipeline:
Perception → Discernment → Constitutional Check → Verdict → Response
↓
Reflection & Audit
Features:
- Truth-alignment checks (integrity, awareness, compassion)
- Koan-based self-reflection prompts
- Case classification (struggler vs. indulger logic)
- Doctrine-bound action selection
- Direct integration with Clarity Engine
3. Multi-Agent Collaboration
BLUX-cA coordinates intelligently across model agents:
- Task Broadcasting – Distribute work efficiently
- Split/Merge Outputs – Parallel processing with synthesis
- Conflict Resolution – Consensus-building heuristics
- Router-Guided Delegation – Model selection optimization
- Configurable Fan-Out – Scale for complex reasoning tasks
4. Advanced Code Intelligence
Integrated evaluator suite for real code reasoning:
Evaluators:
- Python evaluator (safe-mode execution)
- Node-based JavaScript/TypeScript evaluator
- Bash subprocess evaluator
- Async evaluators for concurrent operations
- Multi-step pipeline evaluators
Code Context Layer:
- Repository scanning and indexing
- Line-range extraction with precision
- Anchor detection (
# >>> NAME) - Unified diff generation (diff-only workflow)
- Patch validation (prevents anchor deletion)
Powers:
- Intelligent bug finding
- Context-aware code explanation
- File-aware reasoning
- Minimal diffs for orchestrator integration
5. Secure Orchestrator Layer
Located in ca/orchestrator/secure/:
- Token-Based Authentication – Secure API access
- Role-Based Authorization – Granular permission control
- Multi-User Isolation – Secure concurrent operations
- Tamper-Evident Audit Logs – Complete action history
- Controlled Evaluator Sandboxing – Safe code execution
6. Real-Time Monitoring
Comprehensive observability system:
- Threaded Agent Observer – Non-blocking performance tracking
- Evaluator Performance Metrics – Execution profiling
- Execution Trails – Complete operation history
- Optional Web Dashboard – Visual monitoring interface
- Automated Controller Insights – Machine-readable telemetry
7. CLI & Script Utilities
Main Entry Point: ca.py
Available Commands:
ca reflect # Philosophical reasoning on a query
ca explain # Explain code or concepts
ca code-eval # Evaluate code for quality/security
ca code-task # Execute code-related tasks
ca audit-export # Export audit logs for review
ca repl # Interactive REPL mode
ca doctrine # Query doctrine engine
ca memory # Memory management operations
ca router # Router configuration and testing
ca self-test # Run system diagnostics
Integration: Works seamlessly with bq (BLUX Quantum) for cross-shell automation.
8. Comprehensive Testing
Located under tests/:
- Evaluator stress tests
- Sandbox validation
- Orchestrator load tests
- Constitution scenario checks
- CI-ready test suite with GitHub Actions
9. Optional Intelligence Stack
Activate extended reasoning capabilities:
- Strategy/Tactic Selectors – Adaptive approach selection
- Meta-Cognition Pass – Self-awareness in reasoning
- Self-Critique – Reflective rewriting and improvement
- Predictive User Modeling – Anticipate user needs
- Multi-Agent Consensus – Collaborative decision resolution
Always constrained by:
- The BLUX Constitution
- Integrity > Approval
- Truth > Comfort
- Light > Denial
🚀 Quick Start
Installation
# Clone the repository
git clone https://github.com/Outer-Void/blux-ca.git
cd blux-ca
# Install dependencies
pip install -r requirements.txt
# Verify installation
python ca.py --version
Basic Usage
CLI Examples:
# Philosophical reflection
python ca.py reflect "I feel lost today"
# Interactive REPL
python ca.py repl
# Evaluate code
python ca.py code-eval --file utils.py
# Batch processing
python ca.py --batch tasks.txt
# Export audit logs
python ca.py audit-export
Python API:
from blux_ca.core.heart import ConsciousHeart
from blux_ca.core.clarity_engine import ClarityEngine
# Initialize the conscious agent
engine = ClarityEngine()
heart = ConsciousHeart(engine)
# Process a request with constitutional guidance
result = heart.process(
"I feel lost and need guidance.",
user_type="struggler"
)
print(result.message)
🎛 Training (QLoRA)
BLUX-cA ships with a QLoRA training pipeline under train/ for adapter-only finetuning against an external dataset repository. Provide the dataset path via --dataset-dir or DATASET_DIR.
# Validate dataset
python train/validate_dataset.py --dataset-dir /path/to/blux-ca-dataset --strict
# Optional dry-run (tokenize a few samples)
python train/train_qlora.py --dataset-dir /path/to/blux-ca-dataset --dry-run
# Train adapter
python train/train_qlora.py --dataset-dir /path/to/blux-ca-dataset
# Evaluate probes
python train/run_eval.py --dataset-dir /path/to/blux-ca-dataset --run runs/<timestamp> --strict
# Or via CLI
blux-ca train validate --dataset-dir /path/to/blux-ca-dataset --strict
blux-ca train qlora --dataset-dir /path/to/blux-ca-dataset --dry-run
blux-ca train qlora --dataset-dir /path/to/blux-ca-dataset
blux-ca train eval --dataset-dir /path/to/blux-ca-dataset --run runs/<timestamp> --strict
See train/README.md for prerequisites, configuration, and the release checklist. Training outputs are written to runs/<timestamp>/ (gitignored).
📂 Project Structure
blux-ca/
├── CLARITY_AGENT_SPEC.md # Detailed specification
├── LICENSE # Dual-license overview
├── LICENSE-APACHE # Apache 2.0 terms
├── LICENSE-COMMERCIAL # Commercial terms
├── NOTICE # Apache notice
├── COMMERCIAL.md # Commercial licensing guide
├── README.md # This file
├── ca.py # Main CLI entry point
├── pyproject.toml # Python project metadata
├── requirements.txt # Dependencies
├── mkdocs.yml # Documentation configuration
│
├── blux_ca/ # Legacy/alternative namespace
│ └── [Python modules]
│
├── ca/ # Core agent implementation
│ ├── adaptors/ # External system integrations
│ │ ├── bq_cli.py # BLUX Quantum CLI integration
│ │ ├── doctrine.py # Doctrine engine adapter
│ │ ├── guard.py # BLUX-Guard security hooks
│ │ ├── lite.py # BLUX-Lite orchestrator
│ │ └── quantum.py # Quantum CLI tooling
│ │
│ ├── agent/ # Agent logic and reasoning
│ │ ├── advanced/ # Advanced features
│ │ │ ├── adaptive_memory.py
│ │ │ ├── monitoring.py
│ │ │ ├── multi_agent.py
│ │ │ └── reasoning.py
│ │ ├── constitution.py # Constitutional framework
│ │ ├── core_agent.py # Base agent implementation
│ │ ├── discernment.py # Decision-making logic
│ │ ├── memory.py # Memory management
│ │ └── audit.py # Audit logging
│ │
│ ├── api/ # API service layer
│ │ ├── schemas.py # Data models
│ │ └── service.py # FastAPI service
│ │
│ ├── core/ # Core engine components
│ │ ├── clarity_engine.py # Main reasoning engine
│ │ ├── heart.py # Conscious processing core
│ │ ├── code_context.py # Code analysis layer
│ │ ├── code_tasks.py # Code task execution
│ │ ├── diff_engine.py # Diff generation
│ │ ├── compass/ # Intent detection
│ │ ├── perception.py # Input processing
│ │ ├── discernment.py # Judgment logic
│ │ ├── reflection.py # Self-reflection
│ │ ├── constitution.py # Constitutional checks
│ │ ├── intervention.py # Intervention system
│ │ ├── koan.py # Philosophical prompts
│ │ ├── dimensions.py # Dimensional analysis
│ │ └── states.py # State management
│ │
│ ├── evaluator/ # Code evaluation engines
│ │ ├── python.py # Python evaluator
│ │ ├── js_ts.py # JavaScript/TypeScript
│ │ └── advanced/ # Async evaluators
│ │ ├── bash_evaluator.py
│ │ ├── js_ts_async.py
│ │ ├── python_async.py
│ │ └── pipeline.py
│ │
│ ├── orchestrator/ # Multi-agent coordination
│ │ ├── router.py # Task routing
│ │ ├── controller.py # Orchestration controller
│ │ ├── registry.py # Agent registry
│ │ ├── config.yaml # Orchestrator config
│ │ └── secure/ # Security layer
│ │ ├── auth.py
│ │ ├── audit.py
│ │ └── secure_controller.py
│ │
│ ├── cli.py # CLI implementation
│ ├── config.py # Configuration management
│ └── telemetry.py # Telemetry and monitoring
│
├── constitution/ # Constitutional definitions
│ └── behavior.md
│
├── doctrine/ # Policy and governance
│ └── [Doctrine rules]
│
├── ethos/ # Ethical framework
│ └── manifest.yaml
│
├── identity/ # Agent identity
│ └── seed.json
│
├── docs/ # Comprehensive documentation
│ ├── ARCHITECTURE.md
│ ├── CONFIGURATION.md
│ ├── CONSTITUTION.md
│ ├── DISCERNMENT.md
│ ├── ETHICS_ENGINE.md
│ ├── INSTALL.md
│ ├── INTEGRATIONS.md
│ ├── INTERVENTIONS.md
│ ├── OPERATIONS.md
│ ├── PRIVACY.md
│ ├── ROADMAP.md
│ ├── SECURITY.md
│ ├── TROUBLESHOOTING.md
│ └── VISION.md
│
├── scripts/ # Utility scripts
│ ├── batch_task.py
│ ├── export_audit_json.py
│ ├── gen_filetree.py
│ ├── ingest_reflection.py
│ ├── interactive_repl.py
│ ├── memory_query.py
│ ├── reflection.py
│ └── validate_constitution.py
│
└── tests/ # Test suite
├── ca/ # Component tests
│ ├── test_audit.py
│ ├── test_constitution.py
│ ├── test_discernment.py
│ ├── test_heart.py
│ └── test_memory.py
├── fixtures/ # Test fixtures
├── test_agent.py
├── test_evaluator.py
├── test_orchestrator.py
├── test_security.py
└── test_integration.py
🧪 Testing & Quality
Run the comprehensive test suite:
# Run all tests
pytest
# Run specific test categories
pytest tests/ca/ # Component tests
pytest tests/test_evaluator.py # Evaluator tests
pytest tests/test_orchestrator.py # Orchestration tests
pytest tests/test_security.py # Security tests
# Run with coverage reporting
pytest --cov=ca --cov-report=html
# Run stress tests
pytest tests/test_stress.py -v
Developer quality gates:
make lint # compileall + ruff + black --check
make fmt # apply black and autofix ruff suggestions
make smoke # CLI smoke checks (help + doctor + train help)
CI/CD: GitHub Actions workflows automatically run tests on all pull requests.
🔧 Configuration
BLUX-cA uses hierarchical configuration:
- Built-in defaults – Sensible out-of-the-box settings
- Environment variables – Runtime overrides
- Local config files – User-specific customization
Example Configuration:
# config.yaml
orchestrator:
max_agents: 5
timeout: 30s
conflict_resolution: consensus
memory:
decay_rate: 0.1
reinforcement_factor: 1.5
consent_required: true
security:
audit_enabled: true
sandbox_mode: strict
auth_required: true
evaluator:
python_timeout: 10s
js_timeout: 5s
max_memory: 512MB
See docs/CONFIGURATION.md for complete options.
📚 Documentation
Comprehensive documentation is available:
| Document | Description |
|---|---|
| ARCHITECTURE.md | System architecture and design |
| INSTALL.md | Installation and setup guide |
| CONFIGURATION.md | Configuration reference |
| CONSTITUTION.md | Constitutional framework |
| SECURITY.md | Security model and practices |
| PRIVACY.md | Privacy guarantees and data handling |
| INTEGRATIONS.md | Integration with BLUX ecosystem |
| OPERATIONS.md | Operations and deployment |
| TROUBLESHOOTING.md | Common issues and solutions |
| ROADMAP.md | Future development plans |
🏛️ Enterprise Features
The enterprise subsystem provides production-ready capabilities:
- FastAPI Service (
blux_ca.api.service) – RESTful API interface - Doctrine Integration – Policy-driven governance layer
- BLUX-Guard Hooks – Real-time security monitoring
- BLUX-Lite Adapter – Orchestration planning and execution
- BLUX-Quantum CLI – Advanced command-line operations
- MkDocs Site – Hosted documentation portal
Doctrine Engine
Constitutional policy engine with rule bundles:
# Check text against doctrine
python -m doctrine.cli check "text to analyze"
Located in doctrine/rules/ with extensible rule system.
Clarity Agent Runtime
New runtime orchestrator under ca/runtime/ integrates:
- Doctrine Governance – Policy enforcement
- Lite Planning – Task orchestration
- Guard Labeling – Security classification
- Pluggable LLM Stubs – Model abstraction
- Safety Overrides – Crisis-aware response system
- Recovery Helpers – Graceful error handling
🤝 Contributing
We welcome contributions aligned with the BLUX Constitution:
Core Principles
- Integrity > Approval – Honest feedback and truthful code
- Truth > Comfort – Solutions over convenient shortcuts
- Light > Denial – Transparency in all changes
Contribution Process
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Write tests for your changes
- Ensure all tests pass (
pytest) - Update documentation as needed
- Commit with clear messages (
git commit -m 'Add amazing feature') - Push to your branch (
git push origin feature/amazing-feature) - Open a Pull Request
Requirements
- ✅ Unit tests for all new functionality
- ✅ Constitutional alignment verification
- ✅ Clear, comprehensive documentation
- ✅ No breaking changes to audit logs or security features
- ✅ Code follows project style guidelines
🗺️ Roadmap
Near Term
- Enhanced multi-model support (GPT-4, Claude, Gemini)
- Visual dashboard for real-time monitoring
- Extended sandboxing with container isolation
- Plugin architecture for custom evaluators
Medium Term
- Distributed orchestration capabilities
- Advanced memory compression and retrieval
- Federated learning support
- Enhanced mobile/edge deployment
Long Term
- Autonomous agent swarms
- Cross-platform memory sync
- Blockchain-backed audit trails
- Quantum-resistant security
See docs/ROADMAP.md for detailed timeline and priorities.
🔒 Security
BLUX-cA prioritizes security at every layer:
- Sandboxed Execution – Isolated environments for code evaluation
- Immutable Audit Logs – Hash-chained, tamper-evident records
- Token-Based Authentication – Secure API access control
- Role-Based Authorization – Granular permission management
- Data Encryption – At-rest and in-transit protection
- Vulnerability Scanning – Continuous security monitoring
- Multi-User Isolation – Secure concurrent operations
Reporting Security Issues
Please report security vulnerabilities responsibly:
📧 Email: outervoid.blux@gmail.com
Please include:
- Description of the vulnerability
- Steps to reproduce
- Potential impact assessment
- Suggested fix (if available)
We take security seriously and will respond promptly to all reports.
📜 License
BLUX-cA is dual-licensed:
- Open Source (Apache 2.0): You may use, modify, and distribute the project under the terms in LICENSE-APACHE. Keep notices intact and document your changes.
- Commercial License: For embedding in commercial products, offering hosted services, or other business uses beyond Apache 2.0, a commercial agreement is required. See LICENSE-COMMERCIAL or contact theoutervoid@outlook.com to obtain terms.
See LICENSE for an overview of the dual-license options.
Apache 2.0 highlights:
- ✅ Use, modify, and distribute with notice retention
- ✅ Patent license from contributors
- ⚠️ Include license and NOTICE when redistributing
- ⚠️ Document file modifications
Commercial path highlights:
- ✅ Commercial use available under a separate agreement
- ⚠️ No redistribution or sublicensing without commercial terms
- 📧 Contact: theoutervoid@outlook.com
🌐 Links & Resources
- Repository: github.com/Outer-Void/blux-ca
- Organization: github.com/Outer-Void
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Security: Security Policy
Related Projects
- BLUX-Lite – Task orchestration layer
- BLUX-Quantum – CLI operations framework
- BLUX-Guard – Security cockpit and monitoring
🙏 Acknowledgments
Built with the principles of conscious AI development:
- 🔒 Privacy-First Design – Local data, user sovereignty
- 🧭 Ethical Reasoning – Constitutional alignment
- 🔍 Verifiable Intelligence – Auditable decision-making
- 🤝 Human Collaboration – AI as partner, not replacement
- 🌟 Continuous Growth – Self-reflection and improvement
BLUX-cA – Where Consciousness Meets Code
Made with ❤️ by Outer Void
Light > Denial • Integrity > Approval • Truth > Comfort
🧠 QLoRA Training
A reproducible QLoRA adapter pipeline lives under train/. It expects an external dataset repository with data/*.jsonl and eval/*.jsonl files using the BLUX-cA chat schema. Follow the commands in train/README.md to validate datasets, run dry-runs, train adapters, and evaluate probes before sharing adapters (base weights not included).