Metadata-Version: 2.4
Name: govagent
Version: 0.1.1
Summary: The Governance-First Framework for Agentic AI
Project-URL: Homepage, https://github.com/thekakodkar/govagent
Author-email: Your Name <niraj.kakodkar@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agents,ai,enterprise,governance,roi
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.0
Description-Content-Type: text/markdown

# GovAgent: The Enterprise Protocol for Agentic AI

**The Governance-First Framework for Production-Grade Autonomous Systems.**

`GovAgent` is a high-abstraction, lightweight Python framework designed to bridge the gap between experimental AI and business-critical operations. 

## 🎯 Value Proposition
In high-stakes environments, the barrier to AI adoption is **reliability and control**. `GovAgent` ensures every action is transparent, budget-aware, and risk-managed.

* **Active Circuit Breakers:** Real-time enforcement of financial and operational limits.
* **Governance-as-Code:** Human-readable permission manifests (`policy.yaml`) that align technical execution with organizational policy.
* **Forensic Telemetry:** Standardized audit logs and ROI projections.
* **Zero-Trust Tooling:** Strict whitelisting for agent actions and domain access.

---

## 🏗️ Core Pillars

### 1. The Governance Manifest (`policy.yaml`)
Define "Rules of Engagement" outside the codebase. This allows stakeholders to review and approve agent permissions.
* **Financial Guardrails:** Hard limits on USD spend per session.
* **Action Scopes:** Explicit whitelisting of approved tools.
* **Escalation Triggers:** Thresholds for Human-in-the-Loop (HITL) intervention.

### 2. Forensic Telemetry (`telemetry.py`)
Every execution generates a **Business Value Summary**:
* **ROI Projection:** Estimated manual human-hours saved.
* **Audit Chain:** A verifiable history of every decision, tool call, and result.

---

## 🚧 Development Status (WIP)
**GovAgent is rapidly evolving.** We are currently moving from architectural design to core module implementation.

### ✅ Completed Modules
* **Governance Manifest (`policy.py`):** Structured YAML-based policy enforcement.
* **Forensic Telemetry (`telemetry.py`):** Real-time ROI and audit trail generation.
* **Circuit Breakers (`guards.py`):** Financial and operational risk mitigation logic.
* **Human-in-the-Loop (`hitl.py`):** Managed intervention state.
* **The Executive Loop (`agent.py`):** A "Think-Guard-Act" orchestration engine.

### 🛠️ In Active Development
* **Standardized Tool Registry:** A type-safe way to map business functions to agent capabilities.
* **Mock Model Client:** A testing utility to simulate LLM responses without incurring API costs.
* **HITL Connectors:** Initial hooks for manual approval via CLI.

---

## 📖 Usage Example: Controlled Execution

GovAgent allows you to wrap any AI task in a protective governance layer. 

```python
from govagent import ExecutiveAgent, Policy

# Load your enterprise SOP
policy = Policy.from_yaml("market_research_policy.yaml")

# Run the agent with real-time circuit breakers
agent = ExecutiveAgent(persona="Analyst", policy=policy, model_client=my_llm)
report = await agent.execute("Research competitor pricing")

print(f"Audit Trace: {report.audit_id}")
print(f"Budget Consumed: ${report.estimated_cost_usd}")
```

---

## 🤝 Call for Contributions
We are building GovAgent to be the industry standard for accountable AI. We welcome collaborators from both technical and strategic backgrounds.

### 👩‍💻 Technical Contributions
* **Cloud Adapters:** Help us build exporters for `telemetry.py` logs to AWS CloudWatch, Azure Monitor, or ELK stacks.
* **HITL Integration:** We need native connectors for Slack and Microsoft Teams "Approve/Reject" workflows.
* **Performance:** Optimizing the async reasoning loop for high-concurrency environments.

### 👔 Strategic Contributions
* **Standard Policy Library:** Help us draft pre-built `policy.yaml` templates for common enterprise roles (e.g., "Legal Researcher," "Data Entry Clerk," "Code Auditor").
* **Reporting Tools:** Help design "Reasoning Visualizers" that turn Audit Trail JSON into executive-ready PDF reports.

---

## 💡 Future Ideas
* **Cross-Provider Arbitrage:** Dynamic routing to the most cost-effective model based on task complexity.
* **Digital Twin Governance:** Agents that simulate red-team attacks on your own governance policies.

---
**"Governance is not a constraint; it is the catalyst for enterprise AI adoption."**

---

### Author Stamp
* **Framework:** GovAgent v0.1.0 (Public Release)
* **Status:** Active / Open-Source Standard
* **Compliance:** Designed for Enterprise-Grade Accountability
