Metadata-Version: 2.4
Name: dagonlayer
Version: 0.1.0
Summary: A configuration-driven, deterministic, multi-agent orchestration engine.
Author: timBrockman
License: MIT
Project-URL: Homepage, https://github.com/timBrockman/dagonlayer
Project-URL: Repository, https://github.com/timBrockman/dagonlayer
Keywords: workflow,orchestration,multi-agent,pydantic,llm
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-ai>=0.1.0
Requires-Dist: openai>=1.0.0
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-asyncio; extra == "test"
Dynamic: license-file

# DAGonLayer | A Configuration-Driven, Deterministic, Multi-Agent Engine
## 📂 Lightweight Data-Driven Multi-Agent Orchestrator

A minimalist, high-performance, prototype Python framework for orchestrating specialized multi-agent workflows. By pairing a Strict Configuration-Driven Scheduler with an immutable Unified Provenance Graph, this architecture eliminates conversational prompt drift, slashes token overhead, and provides a reliable execution audit trail.

------------------------------
## 🚀 Key Framework Features

* 📜 Configuration-Driven Routing (YAML): No nested Python if/elif statements. Workflows, edge transitions, and states are defined completely in a declarative YAML file.
* 🛡️ Boundary Protection (Pydantic Guards): Every agent output is tightly validated against strict types before it hits the state layer. Malformed LLM outputs are caught and blocked at the runtime border.
* 🔄 Automated Self-Healing Loop: If an LLM breaks a Pydantic validation rule, the framework captures the structural error message and funnels it back to the agent with instructions to rewrite the response.
* 👥 First-Class Human Intervention (HITL): When agents exhaust their max retries, tasks gracefully route to human queues using identical context-mapping logic—preventing system crashes.
* 🔀 Conditional Expressions: Workflows branch dynamically based on payload evaluation metrics (e.g., checking score values or quality metrics).
* ⚡ Asynchronous Concurrency: Built from the ground up using asyncio to execute thousands of unique workflows in parallel without thread-locking or data cross-contamination.

------------------------------
## 🛠️ Complete Usage Guide
### 1. Define the Workflow Configuration (`workflow.yml`)
The current `workflow.yml` is the declarative state machine for the engine. It defines state transitions, `context_mapping`, `agent` bindings, retry caps, routing rules, and terminal states.

### 2. Run the Entry Point (`main.py`)
The refactor splits the runtime into focused modules and uses `main.py` as the bootstrapper.

```bash
pip install -r requirements.txt
python main.py
```

### 2.1 Package Installation
Install the package locally for importable reuse and CLI execution:

```bash
pip install -e .
python -m dagonlayer
```

### 2.2 Environment Configuration
Use environment variables to configure model selection, logging, tracing, and workflow file path.

```bash
export WORKFLOW_FILE=workflow.yml
export MODEL_ID=openai:gpt-4
export ENABLE_LOGGING=true
export ENABLE_TRACING=true
python -m dagonlayer
```

### 3. How the Engine Works
* `config.py` loads the workflow definition from YAML.
* `orchestrator.py` evaluates states, executes agents, validates outputs, and routes workflow transitions.
* `agents.py` contains the `PydanticAIRegistry` and mock agent implementations, with clear hooks for real Pydantic AI integration.
* `schemas.py` defines strict output contracts and exposes `SCHEMA_REGISTRY` for runtime validation.
* `provenance.py` captures an immutable audit trail for each workflow event.
* `observability.py` instruments execution with logging and trace spans.

## 📊 Architectural Trade-off Matrix
This grid reflects our engineering choices to maintain maximum isolation, token efficiency, and deterministic predictability versus mainstream multi-agent design alternatives.

| Architectural Vector | Choice Made in Framework | Core Strengths | Operational Cost / Vulnerabilities | Practical Alternatives |
|---|---|---|---|---|
| State Tracking Pattern | Immutable Unified Provenance Graph | • Absolute auditing records • Zero tracking state loss • Trivial local troubleshooting playback. | • Memory arrays expand infinitely unless compacted or dropped to disk database lakes. | Dynamic Chat Logs / Blackboard Systems: High operational token drift and easy vector history pollution. |
| Orchestration / Task Routing | Strict External YAML Scheduler | • 100% predictable workflows • Simple, human-readable pipelines • Zero router model overhead costs. | • Brittle when coping with unstructured or random, exploratory workflows. | Autonomous Router Prompts / Swarms: Agents dynamically decide who handles tasks using semantic similarity matches. |
| Agent Input Boundary Interface | Isolated Context Extractor Mapping | • Minimal token windows • Eliminates downstream data leakage or noise hallucinations. | • Tangential, unmapped findings discovered during execution are thrown away. | Shared Context Windows: Entire conversation log maps into every agent call, dramatically expanding context windows. |
| Boundary Protection Strategy | Strict Pydantic Schema Guards | • Fail-safe data pipelines • Automated regex, range, and type validation rules. | • Demands up-front data design models; system halts if unforeseen schemas appear. | Freeform Markdown Text Responses: High processing failure rates down the pipeline due to unparseable response formatting. |

------------------------------
## 🗺️ Future Roadmap Suggestions
### 📦 Phase 0: Package and Stabilize the Refactor
- [x] Create a package entrypoint around `main.py` and expose the orchestrator as a reusable module.
- [x] Add environment configuration for model selection, API keys, and runtime options.
- [x] Verify the new file-level design with stronger tests and clear module contracts.

### 📈 Phase 1: Real Pydantic AI and Production Integration
* Replace mocked agent implementations in `agents.py` with real `pydantic_ai` agent instances.
* Add optional model configuration so the registry can target `openai:gpt-4`, `anthropic:claude-3`, or similar backends.
* Extend observability to export traces to a production telemetry backend.

### 🧠 Phase 2: Persistence and Human Workflow Support
* Add an async persistent store for provenance events so long-running workflows survive restarts.
* Build an actual human intervention queue and callback workflow for `HUMAN_INTERVENTION` state.
* Add webhook/event broker integration so manual review requests can be sent and resumed from external systems.

------------------------------
## 🤝 Advancing the Architecture
This project is a modular prototype built to move beyond a single-file proof of concept. The current refactor makes it easier to extend, validate, test, and eventually connect to real LLMs and production telemetry.
