█████╗ ██████╗ ██████╗██╗ ██╗ ██████╗ ███╗ ██╗
██╔══██╗██╔══██╗██╔════╝██║ ██║██╔═══██╗████╗ ██║
███████║██████╔╝██║ ███████║██║ ██║██╔██╗ ██║
██╔══██║██╔══██╗██║ ██╔══██║██║ ██║██║╚██╗██║
██║ ██║██║ ██║╚██████╗██║ ██║╚██████╔╝██║ ╚████║
╚═╝ ╚═╝╚═╝ ╚═╝ ╚═════╝╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═══╝
Describe data → describe models → describe pipelines → describe policies. Archon compiles your intent into production-ready Python.
Machine learning projects drown in boilerplate. Every team reinvents the same scaffolding — data loaders, model configs, training loops, guardrails. Configuration files drift from implementation. Intent gets lost in translation between Jupyter notebooks, Python scripts, and YAML configs.
Archon treats ML pipelines as compilable artifacts. You describe what you want in a single YAML file, and Archon generates how to do it — with guardrails, policy enforcement, and production-ready code.
# You write THIS (intent):
pipelines:
- name: Support RAG
kind: rag
steps:
- order: 0 | name: load | kind: load
- order: 1 | name: embed | kind: embed | config: { chunk_size: 1000 }
- order: 2 | name: retrieve| kind: retrieve | config: { k: 4 }
- order: 3 | name: generate| kind: generate
# Archon generates THAT (production code):
$ archon generate spec.yaml -o ./generated/
✓ Generated support_rag.py (210 lines)
✓ Generated schema.sql (17 lines) ┌──────────────────────────────────────┐
YAML Intent ─────────▶│ LAYER 1: DSL Schema │
(describe data, │ Pydantic v2 models + YAML/JSON │
models, pipelines, │ loading with validation │
policies) └──────────────┬───────────────────────┘
│ validated spec
┌──────────────▼───────────────────────┐
│ LAYER 2: Pattern Design │
│ 12-entry catalog (4 domains × 3) │
│ Score-based intent → pattern match │
│ domain(0.4) + family(0.3) + kind(0.3)│
└──────────────┬───────────────────────┘
│ matched pattern
┌──────────────▼───────────────────────┐
│ LAYER 3: Code Generation Engine │
│ Jinja2 resolve → dispatch → render │
│ ┌─────────┐ ┌───────────────────┐ │
│ │ Python │ │ SQL Backend │ │
│ │ 4 full │ │ DDL · INSERT · │ │
│ │templates│ │ SELECT per schema │ │
│ └─────────┘ └───────────────────┘ │
└──────────────┬───────────────────────┘
│ generated code
┌───────────────────────────┼───────────────────────────┐
│ │ │
┌──────────▼──────────┐ ┌───────────▼──────────┐ ┌──────────▼──────────┐
│ LAYER 4: Guardrails│ │ LAYER 5: GenAI │ │ LAYER 6: Causal ML │
│ │ │ │ │ │
│ Static (6 checks): │ │ LLMTask ── OpenAI │ │ CausalPipeline │
│ · Reproducibility │ │ RAGPipeline ── │ │ · estimate_ate() │
│ · DAG validity │ │ ChromaDB │ │ · estimate_cate() │
│ · Fairness │ │ ToolAgent ── Agent │ │ · validate() │
│ · Content safety │ │ Executor │ │ + refutation tests │
│ · Monitoring │ │ │ │ │
│ · Explainability │ │ 3 response types │ │ 3 response types │
│ │ │ │ │ │
│ Runtime (4 guards):│ │ Pydantic v2 models │ │ Pydantic v2 models │
│ · Latency budget │ │ Retry + timeout │ │ DoWhy + EconML │
│ · Toxicity filter │ │ Structured logging │ │ Synthetic data OK │
│ · Drift detection │ │ │ │ │
│ · Feature importance│ └──────────────────────┘ └─────────────────────┘
└─────────────────────┘
spec.yaml
│
▼
┌─────────┐ ┌──────────────┐ ┌───────────┐ ┌──────────────┐
│ VALIDATE│───▶│ COMPILE-SPEC │───▶│ GENERATE │───▶│ RUN │
│ Pydantic│ │ 6 static │ │ Jinja2 │ │ Execute + │
│ v2 check│ │ guardrails │ │ rendering │ │ 4 runtime │
└─────────┘ └──────────────┘ └───────────┘ │ guardrails │
└──────────────┘
│
┌──────────────▼──────────────┐
│ Generated Code │
│ .py files · schema.sql │
│ Runnable · Importable │
│ With CLI · Self-contained │
└─────────────────────────────┘
# Install
pip install -e ".[all]"
# Create a spec (or use one from examples/)
cat > my_project.yaml << 'EOF'
archon_version: "1.0.0"
project: quickstart
description: My first Archon pipeline
data:
- name: my_data
domain: tabular
source: ./data.csv
format: csv
features:
- name: x1
dtype: float64
- name: x2
dtype: float64
seed: 42
models:
- name: reducer
family: dim_reduction
algorithm: pca
parameters:
- name: n_components
value: 2
tunable: true
input_schema: my_data
pipelines:
- name: My PCA Pipeline
kind: etl
steps:
- order: 0
name: load
kind: load
config: {}
- order: 1
name: reduce
kind: etl
config:
n_components: 2
datasets: [my_data]
models: [reducer]
policies:
- name: repro
description: Ensure reproducibility
rules:
- name: seed_check
kind: reproducibility
params: {}
EOF
# Validate
archon validate my_project.yaml
# Check guardrails
archon compile-spec my_project.yaml
# Generate production code
archon generate my_project.yaml -o ./generated/
# Run the full pipeline
archon run my_project.yaml
# Browse all 12 patterns in the catalog
archon catalog
|
|
archon validate SPEC # Load and validate a YAML/JSON project spec
archon compile-spec SPEC # Validate + run 6 static guardrails
archon generate SPEC [-o DIR]# Resolve patterns → generate Python + SQL
archon run SPEC [-p NAME] # Full pipeline: validate → guardrails → generate → runtime checks
archon catalog # List all 12 patterns in the catalog
archon llm PROMPT # Run a prompt through any OpenAI model
archon rag QUERY [-s PATH] # Query documents via RAG pipeline
archon causal DATA.csv -t T -o Y # Estimate causal treatment effects
archon agent TASK # Run a tool-using AI agentarchon/
├── archon/
│ ├── config.py # Pydantic BaseSettings, .env, API keys
│ ├── dsl/
│ │ ├── schema.py # 14 Pydantic v2 models + YAML/JSON loader
│ │ └── helpers.py # DAG validation, summarization, domain inference
│ ├── design/
│ │ └── catalog.py # 12-entry catalog, score-based matching engine
│ ├── codegen/
│ │ ├── engine.py # Jinja2 resolve → dispatch → render pipeline
│ │ ├── backends/
│ │ │ └── sql.py # DDL/DML generators from DataSchema
│ │ └── templates/
│ │ ├── rag_advanced.jinja2 # LangChain RAG (210 lines)
│ │ ├── causal_ate.jinja2 # DoWhy/EconML causal (420 lines)
│ │ ├── deep_classifier.jinja2 # PyTorch training (530 lines)
│ │ └── hdim_pca.jinja2 # scikit-learn PCA (270 lines)
│ ├── guardrails/
│ │ ├── static_checks.py # 6 compile-time checks
│ │ ├── runtime.py # 4 runtime guards with real callbacks
│ │ └── constants.py # Shared blocked patterns (10 entries)
│ ├── abstraction/
│ │ ├── genai.py # LLMTask, RAGPipeline, ToolAgent (Pydantic v2)
│ │ └── causal.py # CausalPipeline (DoWhy + EconML)
│ └── cli.py # 9 Typer + Rich commands
├── demo/
│ ├── simulation.py # End-to-end simulation (no API keys needed)
│ └── genomics_pca.yaml # Example DSL spec
├── examples/ # 4 production-ready YAML specs
├── tests/ # 106 tests, 6 test files
├── .github/workflows/ci.yml # CI: test matrix (3.10-3.13), lint, mypy, coverage
├── pyproject.toml # Dependencies, tools, metadata
├── Makefile # test, lint, format, coverage, typecheck, build
├── CHANGELOG.md # Full release history
├── CONTRIBUTING.md # Setup, conventions, PR process
└── SECURITY.md # Vulnerability reporting, best practices
| Layer | Technology |
|---|---|
| DSL | Pydantic v2, PyYAML |
| CLI | Typer, Rich |
| Code Generation | Jinja2 |
| RAG / GenAI | LangChain, OpenAI, ChromaDB |
| Causal ML | DoWhy, EconML, SciPy |
| Deep Learning | PyTorch, scikit-learn |
| Dimensionality Reduction | scikit-learn, UMAP |
| Guardrails | Custom (6 static + 4 runtime) |
| Config / Logging | pydantic-settings, tenacity, httpx |
| Testing | Pytest (106 tests), Coverage (78%) |
| CI/CD | GitHub Actions (4 Python versions) |
| Linting | Ruff, MyPy |
No API keys required — the PCA simulation runs entirely locally:
cd demo
python simulation.pyOutput:
Step 0: Generate 300 samples × 5000 genes (29.5 MB CSV)
Step 1: DSL Validation → Pydantic model ✓
Step 2: Pattern Resolution → hd-pca matched (score=1.0)
Step 3: Static Guardrails → 6/6 checks pass
Step 4: Code Generation → 271-line Python file + SQL schema
Step 5: Execute Generated Code → PCA in 66ms
Step 6: Visualization → 2D scatter + scree plot
Step 7: Runtime Guardrails → 4/4 pass
git clone https://github.com/twomathematicians-code/archon.git
cd archon
pip install -e ".[all,dev]"
pre-commit install
make test # 106 tests
make lint # Ruff
make format # Auto-format
make coverage # Coverage report
make typecheck # MyPyMIT — see LICENSE.
Made with 🔬 by twomathematicians-code