ag2-tealtiger 0.1.0__tar.gz

ag2_tealtiger-0.1.0/.gitignore

@@ -0,0 +1,167 @@
+# Dependencies
+node_modules/
+# package-lock.json committed for Scorecard Pinned-Dependencies compliance
+
+# Build output
+dist/
+build/
+storybook-static/
+*.tsbuildinfo
+
+# Test coverage
+coverage/
+.nyc_output/
+htmlcov/
+.coverage
+.hypothesis/
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Logs
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+
+# OS files
+Thumbs.db
+.DS_Store
+
+# ── SENSITIVE / INTERNAL — DO NOT COMMIT ─────────────────────────
+
+# Internal documentation and planning
+agentguard-internal-docs/
+.kiro/
+
+# Internal analysis and strategy docs (root-level)
+*-INTERNAL-*.md
+*-STRATEGY.md
+*-ANALYSIS.md
+*-FEASIBILITY.md
+*-ALIGNMENT.md
+BRANDING-*.md
+CONTAINERIZATION-*.md
+DEPLOYMENT-*.md
+KUBERNETES-*.md
+PHASE-*.md
+POLICY-REGISTRY-*.md
+POST-LAUNCH-*.md
+TYPESCRIPT-PYTHON-PARITY-*.md
+TEALTIGER-*-ANALYSIS.md
+TEALTIGER-*-ALIGNMENT.md
+TEALTIGER-VS-*.md
+TEALTIGER-PLAYGROUND-*.md
+TEALTIGER-SERVERLESS-*.md
+TEALTIGER-SDK-CONTAINERIZATION-*.md
+TEALTIGER-CLINE-*.md
+DOCKER_README.md
+DOCKER-TEST-RESULTS.md
+
+# Internal scripts
+scripts/*
+!scripts/validate-policy.ts
+!scripts/test-validate-policy.ts
+push-examples.sh
+push-examples.bat
+cleanup-*.bat
+copy-*.bat
+final-*.bat
+remove-*.bat
+update-*.bat
+CLEANUP-ACTION-REQUIRED.txt
+
+# Legacy / deprecated directories
+agentguard/
+agentguard-landing/
+agent-guard-sdk-public/
+test-deprecated/
+test-install/
+tealtiger/
+
+# Infrastructure (should be in separate repos)
+ansible/
+helm/
+helm-charts-repo/
+terraform-aws-tealtiger-repo/
+docker/
+database/
+Dockerfile
+docker-compose*.yml
+
+# Internal source (monorepo backend — not for public SDK repo)
+src/
+!dashboard/governance-feed/src/
+!dashboard/governance-feed/src/**
+
+# Postman collections
+postman/
+
+# Blog drafts and diagrams (published separately)
+blog/
+
+# Internal governance / SOT (separate repo)
+TealTiger-SOT/
+tealtiger-sot-repo/
+
+# Landing pages and websites (separate repos)
+TealTiger-LandingPage/
+TealTiger-Blog/
+TealTiger-Cookbook/
+TealTiger-MCP/
+tealtiger-docs-repo/
+tealtiger-docs-source/
+tealtiger-docs-target/
+tealtiger-action-repo/
+
+# Staging directories (development only)
+staging-py/
+staging-ts/
+
+# Package build artifacts
+package/
+
+# HTML coverage reports
+htmlcov/
+
+# Vertex extension (internal)
+packages/tealtiger-vertex-extension/
+
+# GitHub internal guides
+.github/ENABLE-*.md
+.github/SAMPLE_ISSUES.md
+.github/SOCIAL-PREVIEW-SPEC.md
+
+# Internal workflow files
+.github/workflows/docker-variants.yml
+.github/workflows/publish-circleci-orb.yml
+.github/workflows/v1-1-0-launch.yml
+
+# Build configs (monorepo-level, not needed by SDK users)
+jest.config.js
+.eslintrc.js
+
+# Dashboard package source and lockfile
+!packages/tealtiger-dashboard/src/
+!packages/tealtiger-dashboard/src/**
+!packages/tealtiger-dashboard/package-lock.json
+
+# Misc internal files
+.cleanup-sensitive-files.txt
+*.bat

ag2_tealtiger-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 TealTiger Team
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

ag2_tealtiger-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: ag2-tealtiger
+Version: 0.1.0
+Summary: Deterministic governance adapter for AG2 (AutoGen fork) — policy enforcement, PII detection, cost tracking, per-agent kill switch, governed speaker selection, and structured audit evidence. No LLM in the governance path.
+Project-URL: Homepage, https://tealtiger.ai
+Project-URL: Documentation, https://docs.tealtiger.ai/integrations/ag2
+Project-URL: Repository, https://github.com/agentguard-ai/tealtiger
+Project-URL: Issues, https://github.com/agentguard-ai/tealtiger/issues
+Project-URL: Changelog, https://github.com/agentguard-ai/tealtiger/blob/main/packages/ag2-tealtiger/CHANGELOG.md
+Author-email: TealTiger Team <reachout@tealtiger.ai>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: ag2,ai-agents,audit,autogen,cost-tracking,deterministic,governance,groupchat,guardrails,kill-switch,llm,multi-agent,pii,policy,security,tealtiger
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software 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 :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: ag2>=0.4.0
+Requires-Dist: tealtiger>=1.3.0
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.5.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ag2-tealtiger
+
+Deterministic governance adapter for [AG2](https://github.com/ag2ai/ag2) (AutoGen fork) — policy enforcement, PII detection, cost tracking, per-agent kill switch, governed speaker selection, and structured audit evidence.
+
+**No LLM in the governance path.** All policy evaluation is deterministic, adding <5ms latency.
+
+[![PyPI](https://img.shields.io/pypi/v/ag2-tealtiger)](https://pypi.org/project/ag2-tealtiger/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/ag2-tealtiger)](https://pypi.org/project/ag2-tealtiger/)
+
+## Installation
+
+```bash
+pip install ag2-tealtiger
+```
+
+## Quick Start
+
+### Zero-Config Observe Mode
+
+```python
+from ag2_tealtiger import TealTigerGuard
+
+guard = TealTigerGuard()  # No engine = observe mode
+guard.attach(my_agent)
+# Cost, PII, and tool usage tracked automatically. Nothing blocked.
+```
+
+Or the convenience subclass:
+
+```python
+from ag2_tealtiger import TealTigerAuditAgent
+
+agent = TealTigerAuditAgent(name="coder")  # Zero config, observe mode built-in
+```
+
+### Policy Enforcement
+
+```python
+from ag2_tealtiger import TealTigerGuard, GovernanceMode
+
+guard = TealTigerGuard(engine=my_engine, mode=GovernanceMode.ENFORCE)
+guard.attach(agent)
+# DENY blocks the call with a structured denial message
+```
+
+### Governed GroupChat
+
+```python
+from ag2_tealtiger import GovernedGroupChat, TealTigerGuard, GovernanceMode
+
+guard = TealTigerGuard(engine=engine, mode=GovernanceMode.ENFORCE)
+group_chat = GovernedGroupChat(agents=[agent1, agent2, agent3], guard=guard)
+speaker = group_chat.select_speaker(last_speaker=agent1)
+```
+
+## Features
+
+| Feature | Observe | Monitor | Enforce |
+|---------|:-------:|:-------:|:-------:|
+| Cost tracking per agent | ✅ | ✅ | ✅ |
+| PII detection in tool args | ✅ | ✅ | ✅ |
+| Structured audit entries (TEEC) | ✅ | ✅ | ✅ |
+| Per-agent freeze/unfreeze | ✅ | ✅ | ✅ |
+| Policy evaluation | — | ✅ (log) | ✅ (block) |
+| Budget enforcement | — | ✅ (log) | ✅ (block) |
+| REFER escalation | — | ✅ | ✅ |
+| Inter-agent message governance | ✅ | ✅ | ✅ |
+| Governed speaker selection | ✅ | ✅ | ✅ |
+| JSONL audit export | ✅ | ✅ | ✅ |
+
+## License
+
+Apache-2.0

ag2_tealtiger-0.1.0/README.md

@@ -0,0 +1,74 @@
+# ag2-tealtiger
+
+Deterministic governance adapter for [AG2](https://github.com/ag2ai/ag2) (AutoGen fork) — policy enforcement, PII detection, cost tracking, per-agent kill switch, governed speaker selection, and structured audit evidence.
+
+**No LLM in the governance path.** All policy evaluation is deterministic, adding <5ms latency.
+
+[![PyPI](https://img.shields.io/pypi/v/ag2-tealtiger)](https://pypi.org/project/ag2-tealtiger/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/ag2-tealtiger)](https://pypi.org/project/ag2-tealtiger/)
+
+## Installation
+
+```bash
+pip install ag2-tealtiger
+```
+
+## Quick Start
+
+### Zero-Config Observe Mode
+
+```python
+from ag2_tealtiger import TealTigerGuard
+
+guard = TealTigerGuard()  # No engine = observe mode
+guard.attach(my_agent)
+# Cost, PII, and tool usage tracked automatically. Nothing blocked.
+```
+
+Or the convenience subclass:
+
+```python
+from ag2_tealtiger import TealTigerAuditAgent
+
+agent = TealTigerAuditAgent(name="coder")  # Zero config, observe mode built-in
+```
+
+### Policy Enforcement
+
+```python
+from ag2_tealtiger import TealTigerGuard, GovernanceMode
+
+guard = TealTigerGuard(engine=my_engine, mode=GovernanceMode.ENFORCE)
+guard.attach(agent)
+# DENY blocks the call with a structured denial message
+```
+
+### Governed GroupChat
+
+```python
+from ag2_tealtiger import GovernedGroupChat, TealTigerGuard, GovernanceMode
+
+guard = TealTigerGuard(engine=engine, mode=GovernanceMode.ENFORCE)
+group_chat = GovernedGroupChat(agents=[agent1, agent2, agent3], guard=guard)
+speaker = group_chat.select_speaker(last_speaker=agent1)
+```
+
+## Features
+
+| Feature | Observe | Monitor | Enforce |
+|---------|:-------:|:-------:|:-------:|
+| Cost tracking per agent | ✅ | ✅ | ✅ |
+| PII detection in tool args | ✅ | ✅ | ✅ |
+| Structured audit entries (TEEC) | ✅ | ✅ | ✅ |
+| Per-agent freeze/unfreeze | ✅ | ✅ | ✅ |
+| Policy evaluation | — | ✅ (log) | ✅ (block) |
+| Budget enforcement | — | ✅ (log) | ✅ (block) |
+| REFER escalation | — | ✅ | ✅ |
+| Inter-agent message governance | ✅ | ✅ | ✅ |
+| Governed speaker selection | ✅ | ✅ | ✅ |
+| JSONL audit export | ✅ | ✅ | ✅ |
+
+## License
+
+Apache-2.0

ag2_tealtiger-0.1.0/examples/governed_groupchat.py

@@ -0,0 +1,225 @@
+"""Example: GovernedGroupChat with Speaker Selection.
+
+Demonstrates how GovernedGroupChat applies governance policies to speaker
+selection in multi-agent conversations. In a governed group chat:
+- Frozen agents are skipped without invoking TealEngine
+- Over-budget agents are skipped without invoking TealEngine
+- Remaining candidates are evaluated via TealEngine before getting a turn
+- If all speakers are denied, the round terminates with ALL_SPEAKERS_DENIED
+- REFER decisions suspend an agent while others continue
+
+This is the pattern for multi-agent orchestration with governance guardrails.
+
+Requirements:
+    pip install ag2-tealtiger
+
+Usage:
+    python governed_groupchat.py
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+# ─── Inline mocks so the example runs without real AG2/TealEngine ────────────
+
+
+class MockConversableAgent:
+    """Minimal AG2 ConversableAgent stub for demonstration."""
+
+    def __init__(self, name: str, **kwargs):
+        self.name = name
+        self._reply_funcs: list[dict] = []
+
+    def register_reply(self, trigger=None, reply_func=None, position=0, **kwargs):
+        self._reply_funcs.insert(position, {
+            "trigger": trigger,
+            "reply_func": reply_func,
+        })
+
+    def __repr__(self) -> str:
+        return f"Agent({self.name})"
+
+
+class MockTealEngine:
+    """Mock TealEngine with per-agent speaker selection policies.
+
+    Simulates governance evaluation for speaker candidacy. In production,
+    replace with a real TealEngine and configure policies that determine
+    which agents can speak based on role, context, or risk level.
+
+        from tealtiger import TealEngine
+        engine = TealEngine(policies=[speaker_policy, role_policy, ...])
+    """
+
+    def __init__(self, denied_speakers: list[str] | None = None):
+        """
+        Args:
+            denied_speakers: List of agent names that should be denied
+                when evaluated for speaker candidacy.
+        """
+        self.denied_speakers = denied_speakers or []
+        self.evaluation_count = 0
+
+    def evaluate(
+        self,
+        tool_name: str = "",
+        tool_args: dict[str, Any] | None = None,
+        context: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Evaluate a speaker candidacy or tool call."""
+        self.evaluation_count += 1
+        agent_id = (context or {}).get("agent_id", "")
+
+        if agent_id in self.denied_speakers:
+            return {
+                "action": "DENY",
+                "reason": f"Agent '{agent_id}' not authorized to speak in this round",
+                "reason_codes": ["SPEAKER_DENIED", "ROLE_RESTRICTION"],
+                "risk_score": 60,
+            }
+
+        return {
+            "action": "ALLOW",
+            "reason": "Agent authorized for this conversation round",
+            "reason_codes": ["SPEAKER_ALLOWED"],
+            "risk_score": 0,
+        }
+
+
+# ─── Example: GovernedGroupChat Speaker Selection ────────────────────────────
+
+
+def main() -> None:
+    """Demonstrate GovernedGroupChat with governance-enforced speaker selection."""
+    from ag2_tealtiger import TealTigerGuard, GovernedGroupChat, GovernanceMode
+
+    print("=" * 65)
+    print("  ag2-tealtiger: GovernedGroupChat Speaker Selection")
+    print("=" * 65)
+
+    # ── Setup: Create agents for a coding team ────────────────────────────
+    planner = MockConversableAgent(name="planner")
+    coder = MockConversableAgent(name="coder")
+    reviewer = MockConversableAgent(name="reviewer")
+    executor = MockConversableAgent(name="executor")
+
+    # Create engine that denies the executor from speaking (role restriction)
+    engine = MockTealEngine(denied_speakers=["executor"])
+
+    # Create guard in ENFORCE mode
+    guard = TealTigerGuard(engine=engine, mode=GovernanceMode.ENFORCE)
+
+    # Attach guard to all agents (for tool call governance)
+    for agent in [planner, coder, reviewer, executor]:
+        guard.attach(agent)
+
+    # Create the governed group chat
+    group_chat = GovernedGroupChat(
+        agents=[planner, coder, reviewer, executor],
+        guard=guard,
+        max_round=10,
+        speaker_selection_method="round_robin",
+    )
+
+    # ── Scenario 1: Normal speaker selection with policy filtering ────────
+    print("\n--- Scenario 1: Policy-based speaker selection ---\n")
+
+    selected = group_chat.select_speaker(last_speaker=planner)
+    print(f"  After planner spoke → selected: {selected}")
+    print(f"  (executor is denied by policy, so it gets skipped)")
+
+    selected = group_chat.select_speaker(last_speaker=coder)
+    print(f"  After coder spoke   → selected: {selected}")
+
+    # ── Scenario 2: Frozen agent is skipped without engine call ───────────
+    print("\n--- Scenario 2: Frozen agent skipped ---\n")
+
+    guard.freeze("coder")
+    print(f"  Froze 'coder' — is_frozen: {guard.is_frozen('coder')}")
+
+    # Engine should NOT be called for frozen agents
+    engine.evaluation_count = 0
+    selected = group_chat.select_speaker(last_speaker=planner)
+    print(f"  Selected speaker: {selected}")
+    print(f"  Engine evaluations: {engine.evaluation_count} (frozen agent skipped)")
+
+    guard.unfreeze("coder")
+    print(f"  Unfroze 'coder'")
+
+    # ── Scenario 3: Over-budget agent is skipped ──────────────────────────
+    print("\n--- Scenario 3: Over-budget agent skipped ---\n")
+
+    # Set a low budget for reviewer and exceed it
+    guard.set_budget("reviewer", limit=0.0001)
+    # Simulate cost accumulation to exceed budget
+    guard._budget_manager.track_cost("reviewer", 0.001)
+
+    engine.evaluation_count = 0
+    selected = group_chat.select_speaker(last_speaker=planner)
+    print(f"  Selected speaker: {selected}")
+    print(f"  (reviewer over budget, executor denied by policy)")
+
+    # Check the speaker selection audit
+    audit = group_chat.speaker_selection_audit
+    latest = audit[-1] if audit else None
+    if latest:
+        print(f"\n  Speaker selection audit (last round):")
+        for candidate in latest.candidates_evaluated:
+            print(
+                f"    {candidate['agent_id']:<10} → "
+                f"{candidate['decision']:<6} "
+                f"reason={candidate.get('reason', 'N/A')}"
+            )
+
+    # ── Scenario 4: All speakers denied → round terminates ───────────────
+    print("\n--- Scenario 4: All speakers denied ---\n")
+
+    # Freeze everyone except executor (who is policy-denied)
+    guard.freeze("planner")
+    guard.freeze("coder")
+    # reviewer is already over budget
+
+    selected = group_chat.select_speaker(last_speaker=planner)
+    print(f"  Selected speaker: {selected}")
+    print(f"  (All agents either frozen, over-budget, or policy-denied)")
+
+    # Check the termination audit entry
+    audit = group_chat.speaker_selection_audit
+    latest = audit[-1] if audit else None
+    if latest:
+        print(f"  Reason codes: {latest.reason_codes}")
+
+    # Clean up freezes
+    guard.unfreeze("planner")
+    guard.unfreeze("coder")
+    guard.reset_budget("reviewer")
+
+    # ── Scenario 5: Full audit trail across selection rounds ──────────────
+    print("\n--- Speaker Selection Audit Trail ---\n")
+
+    all_audits = group_chat.speaker_selection_audit
+    print(f"  Total selection rounds: {len(all_audits)}")
+    for i, entry in enumerate(all_audits, 1):
+        print(
+            f"  Round {i}: selected={entry.selected_speaker or 'NONE':<10} "
+            f"candidates={len(entry.candidates_evaluated)} "
+            f"codes={entry.reason_codes}"
+        )
+
+    # ── Key takeaways ─────────────────────────────────────────────────────
+    print("\n" + "=" * 65)
+    print("  Key points:")
+    print("  • GovernedGroupChat evaluates speakers against policies")
+    print("  • Frozen/over-budget agents skipped without engine calls")
+    print("  • Policy-denied agents skipped, next candidate evaluated")
+    print("  • ALL_SPEAKERS_DENIED terminates the round safely")
+    print("  • Full speaker selection audit trail per round")
+    print("  • Per-agent governance isolation in multi-agent groups")
+    print("=" * 65)
+
+
+if __name__ == "__main__":
+    main()