Metadata-Version: 2.4
Name: deepflow-py
Version: 0.1.0
Summary: ODD-min AI Workflow Engine — make AI accountable, auditable, and governable
Project-URL: Homepage, https://github.com/fuyi4it/DeepFlow-py
Project-URL: Documentation, https://deepflow-py.readthedocs.io
Project-URL: Repository, https://github.com/fuyi4it/DeepFlow-py
Project-URL: Zenodo, https://doi.org/10.5281/zenodo.20024964
Author-email: Yi Fu <fuyi.it@live.cn>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,governance,llm,oddframework,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.20
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: all
Requires-Dist: aiokafka>=0.10; extra == 'all'
Requires-Dist: asyncpg>=0.29; extra == 'all'
Requires-Dist: fastapi>=0.111; extra == 'all'
Requires-Dist: uvicorn>=0.30; extra == 'all'
Requires-Dist: websockets>=13.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.9; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29; extra == 'postgres'
Provides-Extra: queue
Requires-Dist: aiokafka>=0.10; extra == 'queue'
Provides-Extra: realtime
Requires-Dist: websockets>=13.0; extra == 'realtime'
Provides-Extra: web
Requires-Dist: fastapi>=0.111; extra == 'web'
Requires-Dist: uvicorn>=0.30; extra == 'web'
Description-Content-Type: text/markdown

# DeepFlow Python

> ODD-min AI Workflow Engine — make AI accountable, auditable, and governable.
>
> The Python implementation of [DeepFlow (UniFlow)](https://github.com/fuyi4it/DeepFlow), grounded in [ODD (Output-Driven Development)](https://doi.org/10.5281/zenodo.20024964) methodology.

---

## What Is This

DeepFlow Python is a workflow engine for AI-generated artifacts. It answers a question no other framework answers:

> **How do I know what the AI produced is what I asked for, who authorized it, and can I take it back?**

Three capabilities make this concrete:

| Capability | What It Does |
|-----------|-------------|
| **Contract** | Define what a valid artifact looks like before the AI produces it |
| **Evidence** | Every run records what was asked, what was produced, and who (or what) approved it |
| **Seal / Rollback** | Lock approved outputs in place; if something goes wrong, roll back to a known-good state |

This is not a wrapper around LangChain. It sits on a different layer: **governance over execution**.

---

## Install

```bash
pip install deepflow
```

Requires Python 3.11+.

---

## Quick Start

```python
from deepflow import Workflow, Contract, LLMAdapter

# 1. Define what "good output" means
contract = Contract(
    name="summary",
    schema={"text": str, "confidence": float},
    must_not_change=["system_prompt"],
)

# 2. Build a workflow that enforces it
wf = Workflow("summarize")
wf.add_step("call_llm", action="llm", prompt="Summarize: {{input.text}}")
wf.add_step("validate", guard=contract)  # rejects if contract is violated
wf.add_step("seal", seal=True)           # locks the result with evidence

# 3. Run
result = wf.run(
    {"text": "..."},
    llm=LLMAdapter.openai(api_key="..."),
)

print(result.output)          # the artifact
print(result.evidence)        # full audit trail
print(result.seal_id)         # immutable reference to this version
```

---

## What It Is Not

- Not a LangChain/CrewAI competitor — different layer
- Not a replacement for code review — it governs AI outputs, not human code
- Not a general-purpose workflow engine — it is designed for AI-native, high-throughput artifact production

---

## Relationship to the Delphi Version

The original DeepFlow is a 112K LOC Delphi application (v1.0.0, December 2025) that has passed M1–M6 verification milestones. This Python version is a full rewrite targeting the Python ecosystem, with an identical ODD-min 5-field ABI:

| Delphi | Python |
|--------|--------|
| `DeepFlow.Workflow.Definition` | `deepflow.workflow.definition` |
| `DeepFlow.Workflow.Executor` | `deepflow.workflow.executor` |
| `DeepFlow.Audit.*` | `deepflow.security.audit` |
| `DeepFlow.Skill.*` | `deepflow.skill.*` |
| `DeepFlow.EventSourcing.*` | `deepflow.events.*` |

---

## Methodology

Built on [ODD (Output-Driven Development)](https://doi.org/10.5281/zenodo.20024964) — an engineering governance protocol for AI-produced artifacts. ODD's core claim:

> In AI-assisted engineering, what needs governing is not "what the model said" but "which artifacts are allowed into the system, and whether they can be verified, sealed, and recalled."

ODD is published on Zenodo (DOI: 10.5281/zenodo.20024964) and has been publicly reviewed.

---

## License

MIT (code). CC-BY-4.0 (documentation and academic materials).
