# Open Agent Compliance Protocol (OACP)
A governance layer for LangGraph that adds voting, consensus, and audit trails to multi-agent workflows. OACP transforms your agent systems with democratic decision-making, adaptive prompting, and comprehensive oversight.
## Overview
OACP provides a framework for building trustworthy multi-agent systems by adding governance mechanisms on top of LangGraph. It enables agents to vote on decisions, reach consensus, maintain audit trails, and adapt their behavior based on feedback.
## Key Features
- **Governance Layer**: Add voting and consensus mechanisms to any LangGraph workflow
- **Adaptive Prompting**: Automatically improve prompts based on rejection feedback
- **Audit Trails**: Complete logging and tracking of all agent decisions and votes
- **Multiple Storage Backends**: File, SQLite, and PostgreSQL support
- **Voting Strategies**: Unanimous, majority, and weighted voting systems
- **Retry Logic**: Intelligent retry mechanisms with exponential backoff
- **LLM Integration**: Built-in adapters for popular language models
- **CLI Tools**: Command-line interface for management and monitoring
## Installation
### From Source
```bash
git clone https://github.com/your-org/oacp.git
cd oacp
pip install -e .
```
### Dependencies
OACP requires Python 3.10+ and depends on:
- **LangGraph**: Core workflow framework
- **Pydantic**: Data validation and settings
- **SQLAlchemy**: Database abstraction layer
- **Typer**: CLI framework
- **Rich**: Terminal formatting
Optional dependencies:
- **psycopg**: PostgreSQL support
- **FastAPI**: Web interface
- **Google Generative AI**: Gemini integration
## Quick Start
### Basic Usage
```python
from oacp import with_oacp, decision_contract, vote, VoteDecision
from langgraph.graph import StateGraph
# Wrap any function with OACP governance
@with_oacp(
role="researcher",
invariants=["factual_accuracy", "comprehensive_coverage"],
log_inputs=True,
log_outputs=True
)
def research_agent(research_request: dict) -> dict:
"""Conducts initial research on the given topic."""
# Your agent logic here
return {"research_results": "..."}
# Create decision contracts for consensus
@with_oacp(
role="synthesizer",
contract=decision_contract(
required_approvers=["researcher", "analyst", "critic"],
strategy="unanimous",
timeout_seconds=30
)
)
def synthesis_agent(data) -> dict:
"""Synthesizes inputs into final report (requires consensus)."""
# Your synthesis logic here
return {"final_report": "..."}
# Voting functions
def researcher_vote(run_id: str, content: str):
if meets_standards(content):
vote(run_id=run_id, voter_id="researcher",
decision=VoteDecision.APPROVE,
reason="Content meets research standards")
else:
vote(run_id=run_id, voter_id="researcher",
decision=VoteDecision.REJECT,
reason="Insufficient research depth")
```
### LangGraph Integration
```python
from langgraph.graph import StateGraph
# Create your workflow
workflow = StateGraph(YourState)
workflow.add_node("research", research_agent)
workflow.add_node("synthesis", synthesis_agent)
workflow.add_edge("research", "synthesis")
# OACP governance is automatically applied
app = workflow.compile()
```
## Examples
### Research Team Workflow
A multi-agent research team with four specialized agents:
```bash
cd examples/research_team
export GOOGLE_AI_API_KEY=your_api_key
python main.py
```
Features demonstrated:
- Multi-agent collaboration
- Consensus-based decision making
- Real LLM integration (Gemini 2.5 Flash)
- Audit trails and governance
### Flappy Bird Game Design
Agent-based game design with component compatibility voting:
```bash
cd examples/flappy_bird_sim
python main.py
```
Features demonstrated:
- Component compatibility validation
- Quality control through voting
- Design iteration with feedback
## Architecture
### Core Components
- **Decorators** (`@with_oacp`, `wrap_node`): Apply governance to functions
- **Contracts**: Define voting requirements and strategies
- **Votes**: Cast and track voting decisions
- **Context**: Access current execution context
- **Storage**: Pluggable storage backends
- **Events**: Comprehensive event system
- **Adaptive Prompting**: Automatic prompt improvement
### Storage Backends
- **File Storage**: JSON-based local storage
- **SQLite**: Lightweight database storage
- **PostgreSQL**: Production-ready database storage
### Voting Strategies
- **Unanimous**: All voters must approve
- **Majority**: More than 50% approval required
- **Weighted**: Votes have different weights
## Configuration
### Environment Variables
```bash
# Storage configuration
OACP_STORAGE_TYPE=sqlite
OACP_STORAGE_URL=sqlite:///oacp.db
# PostgreSQL example
OACP_STORAGE_TYPE=postgresql
OACP_STORAGE_URL=postgresql://user:pass@localhost/oacp
# File storage example
OACP_STORAGE_TYPE=file
OACP_STORAGE_PATH=./oacp_data
```
### Programmatic Configuration
```python
from oacp.storage import configure_storage
# Configure storage backend
configure_storage(
storage_type="sqlite",
storage_url="sqlite:///my_oacp.db"
)
```
## CLI Usage
OACP includes a command-line interface for management:
```bash
# View recent activity
oacp logs --limit 50
# Show statistics
oacp stats
# Export audit trail
oacp export --format json --output audit.json
# View voting patterns
oacp votes --agent researcher --days 7
```
## Development
### Setup Development Environment
```bash
git clone https://github.com/your-org/oacp.git
cd oacp
pip install -e ".[dev]"
pre-commit install
```
### Running Tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=oacp --cov-report=html
# Run specific test file
pytest tests/test_decorators.py
```
### Code Quality
```bash
# Format code
black oacp tests
# Lint code
ruff check oacp tests
# Type checking
mypy oacp
```
## API Reference
### Core Decorators
- `@with_oacp()`: Apply OACP governance to functions
- `wrap_node()`: Wrap LangGraph nodes with governance
### Decision Making
- `decision_contract()`: Define voting requirements
- `vote()`: Cast votes on decisions
- `VoteDecision`: Vote decision enum (APPROVE, REJECT, ABSTAIN)
### Context Access
- `current_context()`: Access current execution context
- `get_adaptation_statistics()`: View adaptive prompting stats
### Storage Interface
- `IStorage`: Abstract storage interface
- `FileStorage`: File-based storage implementation
- `SqliteStorage`: SQLite storage implementation
- `PostgresStorage`: PostgreSQL storage implementation
## Contributing
We welcome contributions! Please see our contributing guidelines:
1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Ensure code quality checks pass
5. Submit a pull request
### Development Guidelines
- Follow PEP 8 style guidelines
- Write comprehensive tests
- Update documentation for new features
- Use type hints throughout
- Add docstrings for public APIs
## License
This project is licensed under the MIT License. See the LICENSE file for details.
## Support
- **Documentation**: Full documentation available in the `docs/` directory
- **Issues**: Report bugs and request features on GitHub Issues
- **Examples**: See `examples/` directory for working implementations
- **CLI Help**: Run `oacp --help` for command-line usage
## Roadmap
- Integration with more LLM providers
- Advanced voting strategies
- Web-based monitoring dashboard
- Distributed agent coordination
- Performance optimizations
- Enhanced adaptive prompting algorithms
## Version
Current version: 0.1.0 (Beta)
OACP is under active development. APIs may change between versions until 1.0.0 release.
Raw data
{
"_id": null,
"home_page": null,
"name": "OACP",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "langgraph, governance, ai, agents, voting, consensus",
"author": null,
"author_email": "Aditya Jangam <aditya@adityajangam.com>",
"download_url": "https://files.pythonhosted.org/packages/8b/93/5f43c9756017918189603502a7592ea3cdd68ccb13aa5c9cb6b6dd786e3c/oacp-0.1.8.tar.gz",
"platform": null,
"description": "# Open Agent Compliance Protocol (OACP)\r\n\r\nA governance layer for LangGraph that adds voting, consensus, and audit trails to multi-agent workflows. OACP transforms your agent systems with democratic decision-making, adaptive prompting, and comprehensive oversight.\r\n\r\n## Overview\r\n\r\nOACP provides a framework for building trustworthy multi-agent systems by adding governance mechanisms on top of LangGraph. It enables agents to vote on decisions, reach consensus, maintain audit trails, and adapt their behavior based on feedback.\r\n\r\n## Key Features\r\n\r\n- **Governance Layer**: Add voting and consensus mechanisms to any LangGraph workflow\r\n- **Adaptive Prompting**: Automatically improve prompts based on rejection feedback\r\n- **Audit Trails**: Complete logging and tracking of all agent decisions and votes\r\n- **Multiple Storage Backends**: File, SQLite, and PostgreSQL support\r\n- **Voting Strategies**: Unanimous, majority, and weighted voting systems\r\n- **Retry Logic**: Intelligent retry mechanisms with exponential backoff\r\n- **LLM Integration**: Built-in adapters for popular language models\r\n- **CLI Tools**: Command-line interface for management and monitoring\r\n\r\n## Installation\r\n\r\n### From Source\r\n\r\n```bash\r\ngit clone https://github.com/your-org/oacp.git\r\ncd oacp\r\npip install -e .\r\n```\r\n\r\n### Dependencies\r\n\r\nOACP requires Python 3.10+ and depends on:\r\n\r\n- **LangGraph**: Core workflow framework\r\n- **Pydantic**: Data validation and settings\r\n- **SQLAlchemy**: Database abstraction layer\r\n- **Typer**: CLI framework\r\n- **Rich**: Terminal formatting\r\n\r\nOptional dependencies:\r\n- **psycopg**: PostgreSQL support\r\n- **FastAPI**: Web interface\r\n- **Google Generative AI**: Gemini integration\r\n\r\n## Quick Start\r\n\r\n### Basic Usage\r\n\r\n```python\r\nfrom oacp import with_oacp, decision_contract, vote, VoteDecision\r\nfrom langgraph.graph import StateGraph\r\n\r\n# Wrap any function with OACP governance\r\n@with_oacp(\r\n role=\"researcher\",\r\n invariants=[\"factual_accuracy\", \"comprehensive_coverage\"],\r\n log_inputs=True,\r\n log_outputs=True\r\n)\r\ndef research_agent(research_request: dict) -> dict:\r\n \"\"\"Conducts initial research on the given topic.\"\"\"\r\n # Your agent logic here\r\n return {\"research_results\": \"...\"}\r\n\r\n# Create decision contracts for consensus\r\n@with_oacp(\r\n role=\"synthesizer\",\r\n contract=decision_contract(\r\n required_approvers=[\"researcher\", \"analyst\", \"critic\"],\r\n strategy=\"unanimous\",\r\n timeout_seconds=30\r\n )\r\n)\r\ndef synthesis_agent(data) -> dict:\r\n \"\"\"Synthesizes inputs into final report (requires consensus).\"\"\"\r\n # Your synthesis logic here\r\n return {\"final_report\": \"...\"}\r\n\r\n# Voting functions\r\ndef researcher_vote(run_id: str, content: str):\r\n if meets_standards(content):\r\n vote(run_id=run_id, voter_id=\"researcher\", \r\n decision=VoteDecision.APPROVE, \r\n reason=\"Content meets research standards\")\r\n else:\r\n vote(run_id=run_id, voter_id=\"researcher\", \r\n decision=VoteDecision.REJECT, \r\n reason=\"Insufficient research depth\")\r\n```\r\n\r\n### LangGraph Integration\r\n\r\n```python\r\nfrom langgraph.graph import StateGraph\r\n\r\n# Create your workflow\r\nworkflow = StateGraph(YourState)\r\nworkflow.add_node(\"research\", research_agent)\r\nworkflow.add_node(\"synthesis\", synthesis_agent)\r\nworkflow.add_edge(\"research\", \"synthesis\")\r\n\r\n# OACP governance is automatically applied\r\napp = workflow.compile()\r\n```\r\n\r\n## Examples\r\n\r\n### Research Team Workflow\r\n\r\nA multi-agent research team with four specialized agents:\r\n\r\n```bash\r\ncd examples/research_team\r\nexport GOOGLE_AI_API_KEY=your_api_key\r\npython main.py\r\n```\r\n\r\nFeatures demonstrated:\r\n- Multi-agent collaboration\r\n- Consensus-based decision making\r\n- Real LLM integration (Gemini 2.5 Flash)\r\n- Audit trails and governance\r\n\r\n### Flappy Bird Game Design\r\n\r\nAgent-based game design with component compatibility voting:\r\n\r\n```bash\r\ncd examples/flappy_bird_sim\r\npython main.py\r\n```\r\n\r\nFeatures demonstrated:\r\n- Component compatibility validation\r\n- Quality control through voting\r\n- Design iteration with feedback\r\n\r\n## Architecture\r\n\r\n### Core Components\r\n\r\n- **Decorators** (`@with_oacp`, `wrap_node`): Apply governance to functions\r\n- **Contracts**: Define voting requirements and strategies\r\n- **Votes**: Cast and track voting decisions\r\n- **Context**: Access current execution context\r\n- **Storage**: Pluggable storage backends\r\n- **Events**: Comprehensive event system\r\n- **Adaptive Prompting**: Automatic prompt improvement\r\n\r\n### Storage Backends\r\n\r\n- **File Storage**: JSON-based local storage\r\n- **SQLite**: Lightweight database storage\r\n- **PostgreSQL**: Production-ready database storage\r\n\r\n### Voting Strategies\r\n\r\n- **Unanimous**: All voters must approve\r\n- **Majority**: More than 50% approval required\r\n- **Weighted**: Votes have different weights\r\n\r\n## Configuration\r\n\r\n### Environment Variables\r\n\r\n```bash\r\n# Storage configuration\r\nOACP_STORAGE_TYPE=sqlite\r\nOACP_STORAGE_URL=sqlite:///oacp.db\r\n\r\n# PostgreSQL example\r\nOACP_STORAGE_TYPE=postgresql\r\nOACP_STORAGE_URL=postgresql://user:pass@localhost/oacp\r\n\r\n# File storage example\r\nOACP_STORAGE_TYPE=file\r\nOACP_STORAGE_PATH=./oacp_data\r\n```\r\n\r\n### Programmatic Configuration\r\n\r\n```python\r\nfrom oacp.storage import configure_storage\r\n\r\n# Configure storage backend\r\nconfigure_storage(\r\n storage_type=\"sqlite\",\r\n storage_url=\"sqlite:///my_oacp.db\"\r\n)\r\n```\r\n\r\n## CLI Usage\r\n\r\nOACP includes a command-line interface for management:\r\n\r\n```bash\r\n# View recent activity\r\noacp logs --limit 50\r\n\r\n# Show statistics\r\noacp stats\r\n\r\n# Export audit trail\r\noacp export --format json --output audit.json\r\n\r\n# View voting patterns\r\noacp votes --agent researcher --days 7\r\n```\r\n\r\n## Development\r\n\r\n### Setup Development Environment\r\n\r\n```bash\r\ngit clone https://github.com/your-org/oacp.git\r\ncd oacp\r\npip install -e \".[dev]\"\r\npre-commit install\r\n```\r\n\r\n### Running Tests\r\n\r\n```bash\r\n# Run all tests\r\npytest\r\n\r\n# Run with coverage\r\npytest --cov=oacp --cov-report=html\r\n\r\n# Run specific test file\r\npytest tests/test_decorators.py\r\n```\r\n\r\n### Code Quality\r\n\r\n```bash\r\n# Format code\r\nblack oacp tests\r\n\r\n# Lint code\r\nruff check oacp tests\r\n\r\n# Type checking\r\nmypy oacp\r\n```\r\n\r\n## API Reference\r\n\r\n### Core Decorators\r\n\r\n- `@with_oacp()`: Apply OACP governance to functions\r\n- `wrap_node()`: Wrap LangGraph nodes with governance\r\n\r\n### Decision Making\r\n\r\n- `decision_contract()`: Define voting requirements\r\n- `vote()`: Cast votes on decisions\r\n- `VoteDecision`: Vote decision enum (APPROVE, REJECT, ABSTAIN)\r\n\r\n### Context Access\r\n\r\n- `current_context()`: Access current execution context\r\n- `get_adaptation_statistics()`: View adaptive prompting stats\r\n\r\n### Storage Interface\r\n\r\n- `IStorage`: Abstract storage interface\r\n- `FileStorage`: File-based storage implementation\r\n- `SqliteStorage`: SQLite storage implementation\r\n- `PostgresStorage`: PostgreSQL storage implementation\r\n\r\n## Contributing\r\n\r\nWe welcome contributions! Please see our contributing guidelines:\r\n\r\n1. Fork the repository\r\n2. Create a feature branch\r\n3. Make your changes with tests\r\n4. Ensure code quality checks pass\r\n5. Submit a pull request\r\n\r\n### Development Guidelines\r\n\r\n- Follow PEP 8 style guidelines\r\n- Write comprehensive tests\r\n- Update documentation for new features\r\n- Use type hints throughout\r\n- Add docstrings for public APIs\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License. See the LICENSE file for details.\r\n\r\n## Support\r\n\r\n- **Documentation**: Full documentation available in the `docs/` directory\r\n- **Issues**: Report bugs and request features on GitHub Issues\r\n- **Examples**: See `examples/` directory for working implementations\r\n- **CLI Help**: Run `oacp --help` for command-line usage\r\n\r\n## Roadmap\r\n\r\n- Integration with more LLM providers\r\n- Advanced voting strategies\r\n- Web-based monitoring dashboard\r\n- Distributed agent coordination\r\n- Performance optimizations\r\n- Enhanced adaptive prompting algorithms\r\n\r\n## Version\r\n\r\nCurrent version: 0.1.0 (Beta)\r\n\r\nOACP is under active development. APIs may change between versions until 1.0.0 release.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Open Agent Compliance Protocol - Governance layer for LangGraph",
"version": "0.1.8",
"project_urls": {
"Documentation": "https://github.com/Aaditya17032002/OACP#readme",
"Homepage": "https://github.com/Aaditya17032002/OACP",
"Issues": "https://github.com/Aaditya17032002/OACP/issues",
"Repository": "https://github.com/Aaditya17032002/OACP"
},
"split_keywords": [
"langgraph",
" governance",
" ai",
" agents",
" voting",
" consensus"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "83518df9ccc1f985442f1b7044077183d17e3416ea45bcbfe0f84d3e3920e519",
"md5": "2aed3481ac25cfcf71ef2b86e5807cd5",
"sha256": "06c5082f0a85d1530c9acec63f8c87c47c3086ef1ebb357bc35ecd355ecae563"
},
"downloads": -1,
"filename": "oacp-0.1.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2aed3481ac25cfcf71ef2b86e5807cd5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 45062,
"upload_time": "2025-08-19T10:13:20",
"upload_time_iso_8601": "2025-08-19T10:13:20.434997Z",
"url": "https://files.pythonhosted.org/packages/83/51/8df9ccc1f985442f1b7044077183d17e3416ea45bcbfe0f84d3e3920e519/oacp-0.1.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8b935f43c9756017918189603502a7592ea3cdd68ccb13aa5c9cb6b6dd786e3c",
"md5": "99e1f3be708a324369370f39eec60dbe",
"sha256": "61a43b44822aaa046d0b80f81f55dea67fc1761e4f9895931d7899f8ed95a620"
},
"downloads": -1,
"filename": "oacp-0.1.8.tar.gz",
"has_sig": false,
"md5_digest": "99e1f3be708a324369370f39eec60dbe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 40180,
"upload_time": "2025-08-19T10:13:22",
"upload_time_iso_8601": "2025-08-19T10:13:22.293224Z",
"url": "https://files.pythonhosted.org/packages/8b/93/5f43c9756017918189603502a7592ea3cdd68ccb13aa5c9cb6b6dd786e3c/oacp-0.1.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-19 10:13:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Aaditya17032002",
"github_project": "OACP#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
],
[
"<",
"3.0.0"
]
]
},
{
"name": "typer",
"specs": [
[
">=",
"0.9.0"
],
[
"<",
"1.0.0"
]
]
},
{
"name": "sqlalchemy",
"specs": [
[
">=",
"2.0.0"
],
[
"<",
"3.0.0"
]
]
},
{
"name": "aiosqlite",
"specs": [
[
"<",
"1.0.0"
],
[
">=",
"0.19.0"
]
]
},
{
"name": "ulid-py",
"specs": [
[
"<",
"2.0.0"
],
[
">=",
"1.1.0"
]
]
},
{
"name": "rich",
"specs": [
[
"<",
"14.0.0"
],
[
">=",
"13.0.0"
]
]
},
{
"name": "langgraph",
"specs": [
[
">=",
"0.0.55"
]
]
},
{
"name": "fastapi",
"specs": [
[
"<",
"1.0.0"
],
[
">=",
"0.104.0"
]
]
},
{
"name": "uvicorn",
"specs": [
[
"<",
"1.0.0"
],
[
">=",
"0.24.0"
]
]
},
{
"name": "pytest",
"specs": [
[
"<",
"8.0.0"
],
[
">=",
"7.0.0"
]
]
},
{
"name": "pytest-asyncio",
"specs": [
[
"<",
"1.0.0"
],
[
">=",
"0.21.0"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
">=",
"4.0.0"
],
[
"<",
"5.0.0"
]
]
},
{
"name": "mypy",
"specs": [
[
"<",
"2.0.0"
],
[
">=",
"1.5.0"
]
]
},
{
"name": "ruff",
"specs": [
[
"<",
"1.0.0"
],
[
">=",
"0.1.0"
]
]
},
{
"name": "black",
"specs": [
[
">=",
"23.0.0"
],
[
"<",
"24.0.0"
]
]
},
{
"name": "pre-commit",
"specs": [
[
">=",
"3.0.0"
],
[
"<",
"4.0.0"
]
]
}
],
"lcname": "oacp"
}
JSON
