README.md

---
license: apache-2.0
library_name: transformers
pipeline_tag: text-generation
tags:
  - clarity-agent
  - constitutional-ai
  - ethics
  - safety
  - reasoning
  - coding
  - multi-domain
language:
  - en
base_model:
  - Qwen/Qwen2.5-7B-Instruct
model_type: lora-adapter
inference: false
---

# BLUX-cA – Clarity Agent

<p align="center">
  <img src="https://raw.githubusercontent.com/Outer-Void/.github/bd4a3ba9bec910bbc2c3bb550925b9bf691a4050/docs/assets/blux-logo.png" alt="BLUX Logo" width="600">
</p>

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![Stars](https://img.shields.io/github/stars/Outer-Void/blux-ca)](https://github.com/Outer-Void/blux-ca/stargazers)

> **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`](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`](docs/DOCTRINE_INTEGRATION.md).
- Training/eval mix and gates: see [`docs/TRAINING_POLICY.md`](docs/TRAINING_POLICY.md).
- Canonical doctrine text lives in the [BLUX Doctrine repository](https://github.com/Outer-Void/blux-doctrine).

### 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:**

```bash
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

```bash
# 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:**

```bash
# 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:**

```python
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`.

```bash
# 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](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:

```bash
# 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:

1. **Built-in defaults** – Sensible out-of-the-box settings
2. **Environment variables** – Runtime overrides
3. **Local config files** – User-specific customization

**Example Configuration:**

```yaml
# 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](docs/CONFIGURATION.md) for complete options.

---

## 📚 Documentation

Comprehensive documentation is available:

| Document | Description |
|----------|-------------|
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | System architecture and design |
| [INSTALL.md](docs/INSTALL.md) | Installation and setup guide |
| [CONFIGURATION.md](docs/CONFIGURATION.md) | Configuration reference |
| [CONSTITUTION.md](docs/CONSTITUTION.md) | Constitutional framework |
| [SECURITY.md](docs/SECURITY.md) | Security model and practices |
| [PRIVACY.md](docs/PRIVACY.md) | Privacy guarantees and data handling |
| [INTEGRATIONS.md](docs/INTEGRATIONS.md) | Integration with BLUX ecosystem |
| [OPERATIONS.md](docs/OPERATIONS.md) | Operations and deployment |
| [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Common issues and solutions |
| [ROADMAP.md](docs/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:

```bash
# 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

1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Write** tests for your changes
4. **Ensure** all tests pass (`pytest`)
5. **Update** documentation as needed
6. **Commit** with clear messages (`git commit -m 'Add amazing feature'`)
7. **Push** to your branch (`git push origin feature/amazing-feature`)
8. **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](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](mailto: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](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](LICENSE-COMMERCIAL) or contact **theoutervoid@outlook.com** to obtain terms.

See [LICENSE](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](https://github.com/Outer-Void/blux-ca)
- **Organization:** [github.com/Outer-Void](https://github.com/Outer-Void)
- **Issues:** [GitHub Issues](https://github.com/Outer-Void/blux-ca/issues)
- **Discussions:** [GitHub Discussions](https://github.com/Outer-Void/blux-ca/discussions)
- **Security:** [Security Policy](https://github.com/Outer-Void/blux-ca/security)

### 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

---

<div align="center">

### BLUX-cA – Where Consciousness Meets Code

**Made with ❤️ by [Outer Void](https://github.com/Outer-Void)**

*Light > Denial • Integrity > Approval • Truth > Comfort*

[![Stars](https://img.shields.io/github/stars/Outer-Void/blux-ca?style=social)](https://github.com/Outer-Void/blux-ca/stargazers)
[![Follow](https://img.shields.io/github/followers/Outer-Void?style=social)](https://github.com/Outer-Void)

</div>

## 🧠 QLoRA Training
A reproducible QLoRA adapter pipeline lives under [`train/`](train/README.md). 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).