Metadata-Version: 2.4
Name: crewai-governance
Version: 0.1.0
Summary: Runtime governance middleware for CrewAI: exit reports, overlap detection, knowledge inheritance.
Author: Alex Salsali
License: MIT
Project-URL: Homepage, https://github.com/asalsali/crewai-governance
Project-URL: Issues, https://github.com/asalsali/crewai-governance/issues
Keywords: crewai,multi-agent,governance,coordination,ai-agents
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: crewai>=0.80.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Dynamic: license-file

# crewai-governance

Runtime governance middleware for CrewAI. Three features, one pip install, zero config.

## What it does

| Feature | Problem it solves | How |
|---------|------------------|-----|
| **Exit reports** | Agents finish and their work disappears. Next run starts from scratch. | Auto-writes structured JSON after every crew run: what each agent did, what worked, token usage. |
| **Overlap detection** | Two crews doing the same work without knowing it. Wasted tokens, conflicting outputs. | Before kickoff, scans active crews for mandate overlap. Warns if detected. |
| **Knowledge inheritance** | New crew runs can't learn from past runs. Same mistakes, same dead ends. | Injects prior exit report summaries into crew context automatically. |

## Install

```bash
pip install crewai-governance
```

## Usage

```python
from crewai import Agent, Task, Crew, Process
from crewai.project import CrewBase, before_kickoff, after_kickoff
from crewai_governance import governance_before_kickoff, governance_after_kickoff

@CrewBase
class ResearchCrew:
    @before_kickoff
    def before(self, inputs):
        return governance_before_kickoff(
            crew_name="research_crew",
            mandate="research AI governance papers"
        )(inputs)

    @after_kickoff
    def after(self, result):
        return governance_after_kickoff("research_crew")(result)

    # ... your agents, tasks, crew as normal
```

That's it. Two lines added to your existing crew class.

## What happens

**First run:** Overlap detection finds nothing. No prior reports to inherit. Your crew runs normally. After completion, an exit report is written to `.crewai-governance/exit_reports/`.

**Second run:** Before kickoff, the middleware injects a summary of the first run's findings into the crew's context. Your agents now know what was already tried. After completion, another exit report is written.

**Parallel runs:** If two crews are running with overlapping mandates, overlap detection warns you before the second one starts.

## Exit report structure

```json
{
  "reportId": "research_crew-1724012345678",
  "crewName": "research_crew",
  "completedAt": "2026-08-20T15:00:00Z",
  "rawOutput": "Found 3 papers on multi-agent governance...",
  "tasksOutput": [
    {
      "description": "Search for recent papers",
      "raw": "Found papers by Smith (2026), Lee (2025)...",
      "agent": "researcher"
    },
    {
      "description": "Summarize findings",
      "raw": "Key themes: coordination failures, trust...",
      "agent": "writer"
    }
  ],
  "tokenUsage": {"total_tokens": 2500},
  "mandateCompleted": true
}
```

## Configuration

```python
from crewai_governance import GovernanceConfig

config = GovernanceConfig(
    storage_dir=".crewai-governance",       # where data lives
    max_inheritance_reports=5,              # how many prior reports to inject
    enable_overlap_detection=True,          # turn overlap checking on/off
    enable_inheritance=True,                # turn inheritance on/off
)

# Pass config to hooks
governance_before_kickoff("my_crew", "my mandate", config)(inputs)
governance_after_kickoff("my_crew", config)(result)
```

## Why this exists

Multi-agent coordination failures account for 37% of all multi-agent system failures ([MAST Failure Taxonomy](https://www.augmentcode.com/guides/why-multi-agent-llm-systems-fail-and-how-to-fix-them)). The top failure modes -- infinite handoff loops, context loss, false consensus -- happen because agents have no memory of what came before and no awareness of what's running alongside them.

This package is the smallest possible intervention: give agents a record of past runs, warn when work overlaps, and let new runs learn from old ones.

## License

MIT
