govagent 0.1.0__tar.gz

govagent-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

govagent-0.1.0/.gitignore

@@ -0,0 +1,181 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor  
+#  Cursor is an AI-powered code editor.`.cursorignore` specifies files/directories to 
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore

govagent-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: govagent
+Version: 0.1.0
+Summary: The Governance-First Framework for Agentic AI
+Project-URL: Homepage, https://github.com/thekakodkar/govagent
+Author: Your Name
+License: MIT
+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 (USD saved vs. USD spent).
+* **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.
+
+---
+
+# GovAgent: Enterprise-Grade Agentic Governance
+
+## 🚧 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. Here is how you enforce a $0.50 budget on a research task:
+
+```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 & Ideas
+We are looking for collaborators to help build:
+1. **Cloud Adapters:** Exporting `telemetry.py` logs to AWS CloudWatch or Azure Monitor.
+2. **Standard Policies:** Pre-built `policy.yaml` templates for common roles (e.g., "Safe Research", "Data Entry", "Code Review").
+3. **Reasoning Visualizers:** A tool to turn the Audit Trail JSON into a readable PDF report for non-technical stakeholders.
+
+---
+**"Governance is not a constraint; it is the catalyst for enterprise AI adoption."**
+---

govagent-0.1.0/README.md

@@ -0,0 +1,74 @@
+# 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 (USD saved vs. USD spent).
+* **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.
+
+---
+
+# GovAgent: Enterprise-Grade Agentic Governance
+
+## 🚧 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. Here is how you enforce a $0.50 budget on a research task:
+
+```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 & Ideas
+We are looking for collaborators to help build:
+1. **Cloud Adapters:** Exporting `telemetry.py` logs to AWS CloudWatch or Azure Monitor.
+2. **Standard Policies:** Pre-built `policy.yaml` templates for common roles (e.g., "Safe Research", "Data Entry", "Code Review").
+3. **Reasoning Visualizers:** A tool to turn the Audit Trail JSON into a readable PDF report for non-technical stakeholders.
+
+---
+**"Governance is not a constraint; it is the catalyst for enterprise AI adoption."**
+---

govagent-0.1.0/examples/governed_researcher.py

@@ -0,0 +1,43 @@
+import asyncio
+from govagent.agent import ExecutiveAgent
+from govagent.policy import Policy
+from govagent.telemetry import TelemetryManager
+
+# Mock Model Client for demonstration (No API key needed)
+class MockModel:
+    async def generate_plan(self, task, persona):
+        # Simulating a thought process and an action
+        return (
+            "I need to search for Q4 trends but the cost is rising.",
+            "web_search",
+            {"query": "2026 tech trends", "source": "verified-news.com"}
+        )
+
+async def main():
+    # 1. Load the Governance Policy
+    policy = Policy.from_yaml("examples/policy.yaml")
+    
+    # 2. Initialize Telemetry and Agent
+    telemetry = TelemetryManager()
+    agent = ExecutiveAgent(
+        persona="Strategic Analyst",
+        policy=policy,
+        model_client=MockModel(),
+        telemetry=telemetry
+    )
+
+    print("--- Starting Governed Task ---")
+    
+    # 3. Execute Task
+    # This will trigger the Think -> Guard -> Act cycle
+    result = await agent.execute("Analyze upcoming 2026 AI market shifts.")
+
+    # 4. Review the Executive Summary
+    print("\n--- Execution Summary ---")
+    print(f"Status: {result.status}")
+    print(f"Final Cost: ${result.estimated_cost_usd:.4f}")
+    print(f"Human Labor Saved: {result.human_minutes_saved} minutes")
+    print(f"Audit ID: {result.trace_id}")
+
+if __name__ == "__main__":
+    asyncio.run(main())

govagent-0.1.0/examples/policy.yaml

@@ -0,0 +1,19 @@
+version: "1.0"
+agent_name: "MarketAnalyst"
+
+# Financial Guardrails
+max_spend_usd: 0.50  # Low limit to demonstrate the circuit breaker
+
+# Action Scopes
+allowed_tools:
+  - "web_search"
+  - "internal_db_query"
+  - "generate_summary"
+
+restricted_domains:
+  - "competitor-alpha.com"
+  - "unverified-leak-site.org"
+
+# Escalation
+require_human_approval: true
+confidence_threshold: 0.90

govagent-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "govagent"
+version = "0.1.0"
+description = "The Governance-First Framework for Agentic AI"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "Your Name", email = ""}
+]
+keywords = ["ai", "agents", "governance", "roi", "enterprise"]
+dependencies = [
+    "pydantic>=2.0.0",
+    "pyyaml>=6.0.0",
+    "httpx>=0.25.0",  # Async-ready for modern LLM APIs
+]
+
+[project.urls]
+"Homepage" = "https://github.com/thekakodkar/govagent"

govagent-0.1.0/src/govagent/agent.py

@@ -0,0 +1,73 @@
+from typing import List, Optional, Any
+from govagent.policy import Policy
+from govagent.guards import CircuitBreaker, GovernanceViolation
+from govagent.telemetry import TelemetryManager
+
+class ExecutiveAgent:
+    """
+    The core execution engine. Orchestrates reasoning while 
+    enforcing governance constraints in real-time.
+    """
+    def __init__(
+        self, 
+        persona: str, 
+        policy: Policy, 
+        model_client: Any,
+        telemetry: Optional[TelemetryManager] = None
+    ):
+        self.persona = persona
+        self.policy = policy
+        self.model = model_client
+        self.guard = CircuitBreaker(policy)
+        self.telemetry = telemetry or TelemetryManager()
+
+    async def execute(self, task: str):
+        """
+        The 'Governed Reasoning' Loop: Think -> Guard -> Act -> Record.
+        """
+        self.telemetry.start_trace(self.persona, task)
+        current_step = 0
+        max_steps = 10 # Safety ceiling
+        
+        try:
+            while current_step < max_steps:
+                # 1. Financial Guard Check
+                self.guard.check_financial_risk(self.telemetry.current_session.estimated_cost_usd)
+                
+                # 2. Reasoning Phase (LLM Call)
+                # Note: This is a conceptual representation of the LLM interaction
+                thought, action, params = await self.model.generate_plan(task, self.persona)
+                
+                # 3. Action Validation Guard
+                # Intercept the intent before execution
+                self.guard.validate_action(action, params)
+                
+                # 4. Human-in-the-Loop Check
+                if self.guard.assess_confidence(0.9) == "ESCALATE_TO_HUMAN":
+                    # Placeholder for HITL protocol (Slack/Teams)
+                    return "Pending Human Approval"
+
+                # 5. Execution & Logging
+                result = await self.perform_action(action, params)
+                self.telemetry.log_step(thought, action, result)
+                
+                if self.is_task_complete(result):
+                    break
+                
+                current_step += 1
+
+            return self.telemetry.finalize(status="success", tokens=1200) # Mock token count
+
+        except GovernanceViolation as gv:
+            # Operationalize the error: Log the violation and stop
+            return self.telemetry.finalize(status=f"blocked: {str(gv)}", tokens=500)
+        except Exception as e:
+            return self.telemetry.finalize(status=f"error: {str(e)}", tokens=0)
+
+    async def perform_action(self, action: str, params: dict):
+        """Placeholder for actual tool execution logic."""
+        return f"Executed {action} with success."
+
+    def is_task_complete(self, result: str) -> bool:
+        """Logic to determine if the agent has reached its goal."""
+        return "complete" in result.lower()

govagent-0.1.0/src/govagent/guards.py

@@ -0,0 +1,43 @@
+from typing import Any, Dict
+from govagent.policy import Policy
+from govagent.telemetry import ExecutionSnapshot
+
+class GovernanceViolation(Exception):
+    """Custom exception for audit-ready error handling."""
+    pass
+
+class CircuitBreaker:
+    """
+    Real-time enforcement of the Governance Manifest.
+    """
+    def __init__(self, policy: Policy):
+        self.policy = policy
+
+    def check_financial_risk(self, current_spend: float):
+        """Prevents further execution if budget is exceeded."""
+        if current_spend >= self.policy.max_spend_usd:
+            raise GovernanceViolation(
+                f"Budget Exceeded: Current spend ${current_spend:.4f} "
+                f"exceeds limit of ${self.policy.max_spend_usd}"
+            )
+
+    def validate_action(self, tool_name: str, parameters: Dict[str, Any]):
+        """
+        Validates the intended action against the whitelist 
+        and inspects for restricted domains.
+        """
+        # Whitelist check
+        if tool_name not in self.policy.allowed_tools:
+            raise GovernanceViolation(f"Unauthorized Tool: {tool_name} is not in the allowed manifest.")
+
+        # Restricted domain check (e.g., blocking specific URLs or IPs)
+        for domain in self.policy.restricted_domains:
+            if any(domain in str(val) for val in parameters.values()):
+                raise GovernanceViolation(f"Access Denied: Parameter contains restricted domain '{domain}'")
+
+    def assess_confidence(self, score: float):
+        """Forces Human-in-the-Loop if AI confidence is low."""
+        if score < self.policy.confidence_threshold:
+            # In a production loop, this would trigger the HITL protocol
+            return "ESCALATE_TO_HUMAN"
+        return "PROCEED"

govagent-0.1.0/src/govagent/policy.py

@@ -0,0 +1,26 @@
+import yaml
+from pydantic import BaseModel, Field
+from typing import List, Optional
+
+class Policy(BaseModel):
+    """The Governance Manifest schema for enterprise control."""
+    version: str = "1.0"
+    agent_name: str
+    
+    # Financial Guardrails
+    max_spend_usd: float = Field(default=1.0, description="Hard limit for API costs")
+    
+    # Action Scopes
+    allowed_tools: List[str] = Field(default_factory=list)
+    restricted_domains: List[str] = Field(default_factory=list)
+    
+    # Escalation
+    require_human_approval: bool = True
+    confidence_threshold: float = 0.85
+
+    @classmethod
+    def from_yaml(cls, file_path: str):
+        """Standardizes the loading of governance policies from YAML files."""
+        with open(file_path, "r") as f:
+            data = yaml.safe_load(f)
+        return cls(**data)

govagent-0.1.0/src/govagent/telemetry.py

@@ -0,0 +1,85 @@
+import time
+import uuid
+from datetime import datetime
+from typing import Dict, Any, Optional
+from pydantic import BaseModel, Field
+
+class ExecutionSnapshot(BaseModel):
+    """
+    A single point-in-time record of an agent's activity.
+    Designed for export to JSON/CSV for compliance reporting.
+    """
+    trace_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    timestamp: str = Field(default_factory=lambda: datetime.utcnow().isoformat())
+    agent_role: str
+    task_input: str
+    
+    # Financial Metrics
+    estimated_cost_usd: float = 0.0
+    tokens_used: int = 0
+    
+    # Performance Metrics
+    latency_seconds: float = 0.0
+    status: str = "initiated"  # initiated, success, failed, human_intervention_required
+    
+    # Business ROI Logic
+    human_minutes_saved: float = 0.0
+    
+    # Audit Trail
+    reasoning_steps: list = []
+
+class TelemetryManager:
+    """
+    Handles the collection and persistence of execution data.
+    Can be extended to push logs to CloudWatch, ELK, or a SQL DB.
+    """
+    def __init__(self, output_path: Optional[str] = "logs/audit_trail.json"):
+        self.output_path = output_path
+        self.current_session: Optional[ExecutionSnapshot] = None
+        self._start_time: float = 0.0
+
+    def start_trace(self, agent_role: str, task: str):
+        """Starts the 'stopwatch' for a specific agent task."""
+        self._start_time = time.perf_counter()
+        self.current_session = ExecutionSnapshot(
+            agent_role=agent_role,
+            task_input=task
+        )
+
+    def log_step(self, thought: str, action: str, result: str):
+        """Appends a reasoning step to the audit trail."""
+        if self.current_session:
+            step = {
+                "timestamp": datetime.utcnow().isoformat(),
+                "thought": thought,
+                "action": action,
+                "result": result
+            }
+            self.current_session.reasoning_steps.append(step)
+
+    def finalize(self, status: str, tokens: int, cost_per_1k: float = 0.02):
+        """
+        Calculates final ROI and latency. 
+        In a real scenario, cost_per_1k would be dynamic based on the model used.
+        """
+        if not self.current_session:
+            return
+
+        self.current_session.latency_seconds = round(time.perf_counter() - self._start_time, 2)
+        self.current_session.status = status
+        self.current_session.tokens_used = tokens
+        self.current_session.estimated_cost_usd = (tokens / 1000) * cost_per_1k
+        
+        # Simple heuristic for ROI: Assumes 1 min of human labor saved for every 5 tokens 
+        # (This logic can be customized per use case)
+        self.current_session.human_minutes_saved = round(tokens / 50, 2) 
+
+        self._persist_log()
+        return self.current_session
+
+    def _persist_log(self):
+        """Writes to a local file—first step toward a full database integration."""
+        if self.output_path and self.current_session:
+            # Here you would implement logic to append to a file or database
+            # For a 'Lite' version, logging to a standard JSONL file is often best.
+            pass