# Orxaq

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://python.org)
[![Tests](https://img.shields.io/badge/tests-550%20passed-brightgreen.svg)]()
[![Coverage](https://img.shields.io/badge/coverage-90%25-brightgreen.svg)]()

**Cognitive causal operating system for credit risk.**

## What is Orxaq?

Credit risk models have a causality problem. Correlation-based models (logistic regression, gradient boosting) learn *what co-occurs* but not *what causes what*. When regulators ask "why did this borrower default?" or "what happens to your portfolio under a 300bp rate shock?", correlation-based models can only extrapolate from training data. They cannot reason about interventions, confounders, or counterfactuals.

Orxaq replaces correlation with causation. It represents the credit economy as a directed acyclic graph (the World DAG) where every edge is a causal mechanism, not a statistical association. PD models are fitted along causal paths. ECL forecasts propagate shocks through the DAG. Fair lending analysis decomposes protected-attribute effects into direct and indirect (through legitimate mediators like employment history).

This design directly addresses regulatory requirements. SR 11-7 demands "conceptual soundness" --- a model grounded in economic theory, not just goodness-of-fit. CECL requires "reasonable and supportable" lifetime loss forecasts. CCAR/DFAST require stress testing under hypothetical scenarios that have never occurred in training data. A causal model handles all three because it models *mechanisms*, not *patterns*.

## Architecture

Orxaq uses a five-ring architecture. Each ring depends only on rings with lower numbers. Ring 1 (Kernel) has zero external dependencies --- stdlib only.

```
Ring 5: Experiences     CLI, Dashboard, API Server, DAG Editor
Ring 4: Orchestration   LLM Providers, Registry, Router
Ring 3: Intelligence    PC, GES, Consensus, D-Sep, Simulator
Ring 2: Data Fabric     Connectors, Schema, Quality Gates, Lineage
Ring 2: Credit Risk     Ontology, PD Model, CECL, Scenarios, Fair Lending
Ring 1: Kernel          WorldDAG, Types, Audit Log, Crypto, Plugins
```

- **Ring 1 --- Kernel**: The type system (`Entity`, `CausalEdge`, `WorldDAG`), hash-chained audit log, crypto primitives, and plugin scaffold. Zero external imports.
- **Ring 2 --- Credit Risk**: 19-variable credit ontology, causal PD model, CECL engine with dynamic horizons, stress testing (CCAR/DFAST), fair lending via causal path decomposition.
- **Ring 2 --- Data Fabric**: CSV/JSON connectors, universal schema validation, data profiling, quality gates, and DAG-based data lineage tracking.
- **Ring 3 --- Intelligence**: Causal discovery via PC and GES, multi-algorithm consensus, d-separation testing, refutation suites, and scenario simulation with Monte Carlo.
- **Ring 4 --- Orchestration**: Multi-provider LLM integration (vLLM, Anthropic, OpenAI) with health checks, model registry, and intelligent task-based routing.
- **Ring 5 --- Experiences**: `orxaq` CLI with `--json` mode, Gamma/Beta/Alpha Observatory skins, live DAG editor, local HTTP API server.

## Quick Start

```bash
pip install orxaq

# Show system status
orxaq status

# Run CECL expected credit loss computation
orxaq credit ecl

# Discover causal structure from data
orxaq discover --variables unemployment_rate,income,credit_score

# Run stress scenario simulation
orxaq simulate --scenario adverse --monte-carlo 1000

# Launch the Observatory dashboard
orxaq serve

# Open the live DAG editor
orxaq edit

# Check LLM provider health
orxaq providers check
```

## CLI Reference

| Command | Description |
|---------|-------------|
| `orxaq status` | Show DAG summary, audit entries, system health |
| `orxaq credit ontology --show` | Display the 19-variable credit ontology |
| `orxaq credit ecl` | Compute CECL expected credit loss |
| `orxaq credit pd` | Predict probability of default |
| `orxaq credit fairness --protected age` | Fair lending decomposition analysis |
| `orxaq discover` | Run causal discovery (PC algorithm) |
| `orxaq discover --consensus` | Run multi-algorithm consensus discovery |
| `orxaq validate` | D-separation validation of the World DAG |
| `orxaq validate --generate` | Generate synthetic validation datasets |
| `orxaq simulate --scenario adverse` | Run scenario shock propagation |
| `orxaq simulate --monte-carlo 1000` | Monte Carlo stress simulation |
| `orxaq fabric ingest data.csv` | Ingest data files |
| `orxaq fabric quality` | Run data quality gates |
| `orxaq fabric profile` | Profile data statistics |
| `orxaq audit --last 10` | Show recent audit log entries |
| `orxaq serve --port 8741` | Launch Observatory dashboard |
| `orxaq edit` | Open live DAG editor in browser |
| `orxaq providers check` | Health-check all LLM providers |
| `orxaq providers list` | List available models across providers |

Add `--json` to any command for machine-readable JSON output:

```bash
orxaq --json credit ecl | jq '.total_ecl'
orxaq --json simulate --scenario adverse | jq '.impact_score'
```

## Deployment

### Docker

```bash
docker build -t orxaq/orxaq:latest .
docker run -p 8741:8741 orxaq/orxaq:latest
```

### Kubernetes (Helm)

```bash
helm install orxaq deploy/helm/ --set image.tag=0.2.0
```

See `deploy/helm/values.yaml` for all configurable parameters.

## Examples

The `examples/` directory contains reference implementations:

| Script | Description |
|--------|-------------|
| `quickstart.py` | End-to-end credit risk workflow in 30 lines |
| `causal_discovery.py` | PC algorithm, consensus discovery, d-separation validation |
| `scenario_simulation.py` | Built-in CCAR scenarios, custom shocks, Monte Carlo |
| `fair_lending.py` | Causal path decomposition for protected attributes |
| `data_quality.py` | Data profiling, quality gates, audit trail |

```bash
python examples/quickstart.py
```

## Development

```bash
git clone https://github.com/Orxaq/orxaq.git
cd orxaq
pip install -e ".[dev]"
make check
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development workflow, and [SECURITY.md](SECURITY.md) for our security policy.

## Project Status

**Current: Alpha (v0.2.0)**

- 550 tests, 90% coverage
- 9 modules shipped: Kernel, Credit Risk, Data Fabric, Causal Discovery, Orchestration, Experiences, Enterprise, Validation, CLI
- 25 Architecture Decision Records ([ADR log](docs/adr/README.md))
- Zero external runtime dependencies
- Docker + Helm deployment ready
- Multi-provider LLM integration (vLLM, Anthropic, OpenAI)

See [CHANGELOG.md](CHANGELOG.md) for release history.

## License

Apache 2.0 --- see [LICENSE](LICENSE).
