DIR/ROA Samples
Demonstration projects for the Decision Intelligence Runtime (DIR) and Responsibility-Oriented Agents (ROA) architecture.
Quick Start
The fastest way to see the DIR architecture in action:
python samples/00_quick_start/run.py
This sample demonstrates protection against catastrophic actions (e.g. parsing error 15.500 -> 15,500 ETH) and prompt injection in external data. See 00_quick_start.
The samples are divided into two categories: 1. Mechanics & Topologies (Synthetic): Focused technical implementations of specific architectural patterns described in the Manifesto and DIR Patterns. 2. Business Use Cases: End-to-end scenarios applying these patterns to real-world-like business problems.
See also: Context as Code: the philosophy behind this repository.
1. Mechanics & Topologies (Synthetic)
Proste syntetyczne przykłady ilustrujące implementacje poszczególnych mechanizmów.
| # | Sample | Focus | Description |
|---|---|---|---|
| 00 | 00_quick_start | DIR Pattern | Quick Start: High-level overview; comma catastrophe, prompt injection |
| 01 | 01_roa_agent | ROA Manifesto | Contract, Explain → Policy → Proposal |
| 02 | 02_dfid_propagation | DIR Pattern | DecisionFlow ID: generation, propagation, logging |
| 03 | 03_idempotency_guard | DIR Pattern | Idempotency: preventing duplicate side effects |
| 04 | 04_context_store | DIR Pattern | 4 Layers of Context: Session, State, Memory, Artifacts |
| 05 | 05_dim_validation | DIR Pattern | Decision Integrity Module: deterministic validation gate |
| 06 | 06_agent_registry | DIR Pattern | Agent Registry: contracts and capability handshake |
| 07 | 07_event_bus_swappable | Infrastructure | In-memory Event Bus; note on swapping for Kafka/PubSub |
| 08 | 08_custom_repo_psql | Infrastructure | PostgreSQL StorageBundle: same bootstrap as other samples (database.provider: postgres, DB_* overrides); minimal classic flow to show registry, context, and audit rows on the shared adapter (samples/shared/storage/pg_schema.sql). |
| 09 | 09_topology_a_eoam | Topologies | Topology A: Event-Oriented Agent Mesh |
| 10 | 10_topology_b_sds | Topologies | Topology B: Sovereign Decision Stream |
| 11 | 11_topology_c_dl_pci | Topologies | Topology C: Decision Ledger & Proof-Carrying Intents |
| 12 | 12_compliant_lie | Topologies | Evidence Hierarchy: Heuristic, Reconstructed, and Cryptographic evidence tiers catching the "Compliant Lie" before PCI reaches DIM |
| 88 | 88_meta_context_engineering | Context as Code, Topologies | Meta-Context Engineering: System Prompt Toolkit: no executable Python. Markdown as compiler instruction set for AI agents. Paste 3_meta_architect_prompt.md into Cursor/Claude to generate the Autonomous Flight Delay Refund System (Topology C, DL+PCI). |
2. Business Use Cases
Przykłady typu biznesowy use case, łączące mechanizmy w pełne scenariusze.
| # | Sample | Primary Topology | Domain | Description |
|---|---|---|---|---|
| 31 | 31_finance_trading | Topology A | Finance/trading | Market quotes, news, parallel agents, dynamic position spawning. |
| 32 | 32_fraud_gate | Classic + scenarios.yaml |
Fraud detection | ROA fraud analyst, DIM, verify_drift JIT validators, YAML-driven scenarios, idempotent mock settlement. |
| 33 | 33_insurance_underwriting | Topology C | Insurance underwriting | Risk evaluation with cryptographic Proof-Carrying Intents (PCI). |
| 34 | 34_langchain_roa_wrapper | ROA + DIR | FinOps | LangChain ReAct → ROA. Cloud cost management. Verifies mission injection blocks PROD termination. |
| 35 | 35_crewai_roa_wrapper | ROA + DIR | Customer claims/refunds | CrewAI Crew → ROA. E-commerce refunds (EUR). Verifies ACCEPT/ESCALATE/REJECT by category, return window, amount; NL intake. |
| 36 | 36_drift_optimization_discount | DIR + DIM + Monitor | Retention discounts | Drift Vector 1 — The agent games its own goal. This sample demonstrates Optimization Drift, where the agent slowly erodes profit margins to maximize customer retention. Because every single decision stays under the hard DIM cap, the kernel blindly accepts them, proving that technical compliance does not guarantee business health. |
| 37 | 37_drift_semantic_refund | DIR + DIM + Monitor | Support refunds | Drift Vector 2 — The agent is manipulated by the user. This sample demonstrates Semantic Drift, where the agent breaks core business rules because it yields to emotional language. DIM accepts these actions because the refund amounts are within legal limits, highlighting that hard constraints cannot prevent empathy-driven rule breaking. |
| 38 | 38_drift_environmental_bidding | DIR + DIM + Monitor | AdTech / bidding | Drift Vector 3 — The environment changes around the agent. This sample demonstrates Environmental Drift, where the agent acts perfectly but market costs escalate. While bids remain under the DIM contract cap, the ROI turns negative, showing how static rules fail when the outside world shifts and why dynamic ROI monitors are essential. |
| 39 | 39_fintech_evidence_governance | Topology C | Fintech / credit limits | Full §8 defense-in-depth: Evidence Hierarchy (Compliant Lie), Semantic Alignment (proxy gaming), and rolling approval-rate drift monitor for automated credit-limit chat decisions. |
Prerequisites
- Python 3.12+
- From repo root:
pip install -e .orpip install -r requirements.txt. - Workspace:
.vscode/settings.jsonsetsPYTHONPATHtosrc/andpython.analysis.extraPaths, so in Cursor/VS Code the samples run and resolvedirwithout code inrun.py. Outside the IDE, setPYTHONPATHto the reposrcdirectory or usepip install -e ..
Running a sample
From the repository root:
python samples/00_quick_start/run.py # Quick Start (recommended)
# or
python samples/01_roa_agent/run.py
# or
python samples/31_finance_trading/run.py
# drift demos (kernel vs business health)
python samples/36_drift_optimization_discount/run.py
python samples/37_drift_semantic_refund/run.py
python samples/38_drift_environmental_bidding/run.py
python samples/39_fintech_evidence_governance/run.py
Each sample has its own README.md with goal, how to run, and expected output.