agentcontrolroom 0.1.0__tar.gz

agentcontrolroom-0.1.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: agentcontrolroom
+Version: 0.1.0
+Summary: The Reliability Layer for Autonomous AI Agents — full tracing, cost intelligence, guardrails, and quality evaluation.
+Author-email: Darshan <darshan@agentcontrolroom.io>
+License: MIT
+Project-URL: Homepage, https://agentcontrolroom.io
+Project-URL: Repository, https://github.com/Darshan-1812/Helm-AI
+Project-URL: Documentation, https://github.com/Darshan-1812/Helm-AI#readme
+Project-URL: Bug Tracker, https://github.com/Darshan-1812/Helm-AI/issues
+Keywords: ai,agents,llm,observability,tracing,langchain,openai,monitoring,guardrails
+Classifier: Development Status :: 4 - Beta
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: opentelemetry-api>=1.25.0
+Requires-Dist: opentelemetry-sdk>=1.25.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2.0; extra == "langchain"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.30.0; extra == "crewai"
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.10.0; extra == "llamaindex"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"

agentcontrolroom-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agentcontrolroom"
+version = "0.1.0"
+description = "The Reliability Layer for Autonomous AI Agents — full tracing, cost intelligence, guardrails, and quality evaluation."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Darshan", email = "darshan@agentcontrolroom.io" },
+]
+keywords = [
+    "ai", "agents", "llm", "observability", "tracing",
+    "langchain", "openai", "monitoring", "guardrails",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+    "opentelemetry-api>=1.25.0",
+    "opentelemetry-sdk>=1.25.0",
+]
+
+[project.urls]
+Homepage = "https://agentcontrolroom.io"
+Repository = "https://github.com/Darshan-1812/Helm-AI"
+Documentation = "https://github.com/Darshan-1812/Helm-AI#readme"
+"Bug Tracker" = "https://github.com/Darshan-1812/Helm-AI/issues"
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.2.0"]
+crewai   = ["crewai>=0.30.0"]
+llamaindex = ["llama-index-core>=0.10.0"]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "ruff>=0.5.0",
+    "build>=1.0.0",
+    "twine>=5.0.0",
+]
+
+[project.scripts]
+acr-check = "agentcontrolroom._cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"agentcontrolroom" = ["py.typed"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100

agentcontrolroom-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agentcontrolroom-0.1.0/src/agentcontrolroom/__init__.py

@@ -0,0 +1,82 @@
+"""
+Agent Control Room SDK
+======================
+
+Reliability Layer for Autonomous AI Agents.
+
+Quick Start (env-var based — zero code config):
+    export ACR_API_KEY=acr-dev-xxxx
+    export ACR_ENDPOINT=https://your-backend.onrender.com
+
+    from agentcontrolroom import trace
+
+    @trace.agent(name="my-agent")
+    def my_agent(query: str):
+        result = llm_call(query)
+        return result
+
+    @trace.tool(name="web-search")
+    def search(query: str):
+        ...
+
+Manual config:
+    from agentcontrolroom import configure, trace
+
+    configure(api_key="acr-dev-xxxx", endpoint="https://...")
+
+    @trace.agent("my-agent")
+    def my_agent(query: str):
+        ...
+"""
+
+from agentcontrolroom._config import get_api_key, get_endpoint, is_configured
+from agentcontrolroom.tracer import trace, Tracer
+from agentcontrolroom.client import ACRClient
+from agentcontrolroom.spans import SpanKind
+from agentcontrolroom.cost import CostCalculator
+from agentcontrolroom.guardrails import Guardrails
+
+__version__ = "0.1.0"
+
+
+def configure(
+    api_key: str,
+    endpoint: str = "http://localhost:8000",
+) -> None:
+    """
+    Configure the global tracer with your API key and backend endpoint.
+
+    This is optional if you set ACR_API_KEY and ACR_ENDPOINT env vars.
+
+    Args:
+        api_key:  Your Agent Control Room API key (e.g. "acr-dev-xxxx")
+        endpoint: URL of your ACR backend (default: http://localhost:8000)
+
+    Example:
+        from agentcontrolroom import configure
+        configure(api_key="acr-dev-xxxx", endpoint="https://acr.myapp.com")
+    """
+    trace.configure(api_key=api_key, endpoint=endpoint)
+
+
+# ── Auto-configure from env vars at import time ───────────────────────────────
+if is_configured():
+    configure(api_key=get_api_key(), endpoint=get_endpoint())
+
+
+__all__ = [
+    # Core
+    "trace",
+    "Tracer",
+    "ACRClient",
+    "SpanKind",
+    "CostCalculator",
+    "Guardrails",
+    # Config helpers
+    "configure",
+    "get_api_key",
+    "get_endpoint",
+    "is_configured",
+    # Version
+    "__version__",
+]

agentcontrolroom-0.1.0/src/agentcontrolroom/__main__.py

@@ -0,0 +1,11 @@
+"""
+Enable `python -m agentcontrolroom` entry point.
+
+Usage:
+    python -m agentcontrolroom check
+    python -m agentcontrolroom check --api-key acr-dev-xxxx --endpoint https://...
+"""
+
+from agentcontrolroom._cli import main
+
+main()

agentcontrolroom-0.1.0/src/agentcontrolroom/_cli.py

@@ -0,0 +1,188 @@
+"""
+acr-check CLI — verify your Agent Control Room setup is working.
+
+Usage:
+    python -m agentcontrolroom check
+    python -m agentcontrolroom check --api-key acr-dev-xxxx --endpoint https://...
+    acr-check                             # if installed via pip
+    acr-check --api-key acr-dev-xxxx
+"""
+
+import argparse
+import sys
+import os
+
+# ── ANSI colours (disabled on Windows if no support) ─────────────────────────
+GREEN  = "\033[92m"
+RED    = "\033[91m"
+YELLOW = "\033[93m"
+CYAN   = "\033[96m"
+BOLD   = "\033[1m"
+RESET  = "\033[0m"
+
+OK   = f"{GREEN}✅{RESET}"
+FAIL = f"{RED}❌{RESET}"
+WARN = f"{YELLOW}⚠️ {RESET}"
+INFO = f"{CYAN}ℹ️ {RESET}"
+
+
+def _print_header():
+    print(f"\n{BOLD}{'=' * 58}{RESET}")
+    print(f"{BOLD}  Agent Control Room — System Health Check{RESET}")
+    print(f"{BOLD}{'=' * 58}{RESET}\n")
+
+
+def _check_backend(client) -> bool:
+    """Check if the backend API is reachable and healthy."""
+    try:
+        health = client.health_check()
+        version = health.get("version", "unknown")
+        print(f"  {OK} Backend reachable  (version: {version})")
+        return True
+    except Exception as e:
+        print(f"  {FAIL} Backend unreachable: {e}")
+        print("       → Is the backend running? Try: docker-compose up -d")
+        return False
+
+
+def _check_auth(client) -> bool:
+    """Verify the API key is valid."""
+    try:
+        resp = client._client.get("/api/v1/runs")
+        if resp.status_code == 401:
+            print(f"  {FAIL} API key invalid — got 401 Unauthorized")
+            print("       → Check your ACR_API_KEY value")
+            return False
+        elif resp.status_code in (200, 422):
+            print(f"  {OK} API key valid")
+            return True
+        else:
+            print(f"  {WARN} Unexpected status {resp.status_code} from /api/v1/runs")
+            return True
+    except Exception as e:
+        print(f"  {FAIL} Auth check failed: {e}")
+        return False
+
+
+def _check_trace_ingest(client) -> bool:
+    """Send a test trace and verify it is ingested."""
+    from agentcontrolroom.spans import RunData, SpanData, SpanKind
+
+    run = RunData(agent_name="acr-health-check", input_text="system health check")
+    span = SpanData(
+        name="health-check-span",
+        span_kind=SpanKind.TOOL,
+        run_id=run.run_id,
+        input_data="ping",
+        output_data="pong",
+        latency_ms=1.0,
+    )
+    span.finish()
+    run.add_span(span)
+    run.finish(output="ok", status="completed")
+
+    try:
+        result = client.send_run(run)
+        ingested = result.get("spans_ingested", 0)
+        print(f"  {OK} Test trace ingested  ({ingested} span(s) stored)")
+        return True
+    except Exception as e:
+        print(f"  {FAIL} Trace ingest failed: {e}")
+        print("       → Is PostgreSQL + Dramatiq worker running?")
+        return False
+
+
+def _check_dashboard(endpoint: str) -> bool:
+    """Verify the frontend dashboard is reachable."""
+    import httpx
+    # Try port 3001 (docker-compose) or 3000 (dev server)
+    for port in [3001, 3000]:
+        url = f"http://localhost:{port}"
+        try:
+            resp = httpx.get(url, timeout=3.0, follow_redirects=True)
+            if resp.status_code < 400:
+                print(f"  {OK} Dashboard reachable at {url}")
+                return True
+        except Exception:
+            continue
+
+    print(f"  {WARN} Dashboard not reachable on :3001 or :3000")
+    print("       → Run: docker-compose up -d frontend")
+    return False
+
+
+def run_check(api_key: str, endpoint: str) -> int:
+    """Run all checks. Returns 0 if all pass, 1 if any fail."""
+    from agentcontrolroom.client import ACRClient
+
+    print(f"  {INFO} Endpoint : {endpoint}")
+    print(f"  {INFO} API Key  : {api_key[:12]}{'*' * max(0, len(api_key) - 12)}\n")
+
+    results = []
+
+    client = ACRClient(api_key=api_key, endpoint=endpoint, auto_flush=False)
+
+    try:
+        results.append(_check_backend(client))
+        if results[-1]:
+            results.append(_check_auth(client))
+            if results[-1]:
+                results.append(_check_trace_ingest(client))
+        results.append(_check_dashboard(endpoint))
+    finally:
+        client.close()
+
+    print()
+    passed = sum(results)
+    total  = len(results)
+
+    if all(results):
+        print(f"{BOLD}{GREEN}{'=' * 58}{RESET}")
+        print(f"{BOLD}{GREEN}  🎉 All checks passed! ({passed}/{total}){RESET}")
+        print(f"{BOLD}{GREEN}  Your Agent Control Room is working correctly.{RESET}")
+        print(f"{BOLD}{GREEN}{'=' * 58}{RESET}\n")
+        return 0
+    else:
+        print(f"{BOLD}{RED}{'=' * 58}{RESET}")
+        print(f"{BOLD}{RED}  {passed}/{total} checks passed — see issues above.{RESET}")
+        print(f"{BOLD}{RED}{'=' * 58}{RESET}\n")
+        return 1
+
+
+def main():
+    _print_header()
+
+    parser = argparse.ArgumentParser(
+        prog="acr-check",
+        description="Verify your Agent Control Room setup is working correctly.",
+    )
+    parser.add_argument(
+        "--api-key",
+        default=os.environ.get("ACR_API_KEY", ""),
+        help="Your ACR API key (default: $ACR_API_KEY)",
+    )
+    parser.add_argument(
+        "--endpoint",
+        default=os.environ.get("ACR_ENDPOINT", "http://localhost:8000"),
+        help="Backend endpoint URL (default: $ACR_ENDPOINT or http://localhost:8000)",
+    )
+
+    # Support `python -m agentcontrolroom check` subcommand
+    if len(sys.argv) > 1 and sys.argv[1] == "check":
+        sys.argv.pop(1)
+
+    args = parser.parse_args()
+
+    if not args.api_key:
+        print(f"  {FAIL} No API key provided.\n")
+        print("  Set it via:")
+        print("    export ACR_API_KEY=acr-dev-xxxx")
+        print("  or:")
+        print("    acr-check --api-key acr-dev-xxxx\n")
+        sys.exit(1)
+
+    sys.exit(run_check(api_key=args.api_key, endpoint=args.endpoint))
+
+
+if __name__ == "__main__":
+    main()

agentcontrolroom-0.1.0/src/agentcontrolroom/_config.py

@@ -0,0 +1,40 @@
+"""
+Agent Control Room — centralized environment-variable configuration.
+
+Reads ACR_API_KEY and ACR_ENDPOINT from the environment so users can configure
+the SDK without writing any Python code:
+
+    export ACR_API_KEY=acr-dev-xxxx
+    export ACR_ENDPOINT=https://your-acr-backend.onrender.com
+
+    # Then in Python — just import, no configure() call needed:
+    from agentcontrolroom import trace
+
+    @trace.agent("my-agent")
+    def my_agent(query: str):
+        ...
+"""
+
+import os
+import logging
+
+logger = logging.getLogger("agentcontrolroom")
+
+# ── Public defaults (read once at import time) ────────────────────────────────
+ACR_API_KEY: str = os.environ.get("ACR_API_KEY", "")
+ACR_ENDPOINT: str = os.environ.get("ACR_ENDPOINT", "http://localhost:8000")
+
+
+def get_api_key() -> str:
+    """Return the currently configured API key (env var or manually set)."""
+    return os.environ.get("ACR_API_KEY", ACR_API_KEY)
+
+
+def get_endpoint() -> str:
+    """Return the currently configured backend endpoint."""
+    return os.environ.get("ACR_ENDPOINT", ACR_ENDPOINT)
+
+
+def is_configured() -> bool:
+    """Return True if an API key is available."""
+    return bool(get_api_key())

agentcontrolroom-0.1.0/src/agentcontrolroom/client.py

@@ -0,0 +1,149 @@
+"""
+HTTP Client — ships trace data to the Agent Control Room backend.
+Supports batching and async flush.
+"""
+
+import threading
+import time
+import logging
+from typing import Optional
+
+import httpx
+
+from agentcontrolroom.spans import RunData
+
+logger = logging.getLogger("agentcontrolroom")
+
+
+class ACRClient:
+    """
+    HTTP client for Agent Control Room.
+
+    Usage:
+        client = ACRClient(
+            api_key="acr-dev-xxxx",
+            endpoint="http://localhost:8000",
+        )
+
+        # Ship a complete run
+        client.send_run(run_data)
+
+        # Or use auto-flush with batching
+        client.queue_run(run_data)
+        client.flush()  # or let background thread flush
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        endpoint: str = "http://localhost:8000",
+        batch_size: int = 10,
+        flush_interval: float = 5.0,
+        timeout: float = 30.0,
+        auto_flush: bool = True,
+    ):
+        self.api_key = api_key
+        self.endpoint = endpoint.rstrip("/")
+        self.batch_size = batch_size
+        self.flush_interval = flush_interval
+        self.timeout = timeout
+
+        self._queue: list[RunData] = []
+        self._lock = threading.Lock()
+        self._client = httpx.Client(
+            base_url=self.endpoint,
+            headers={
+                "X-API-Key": self.api_key,
+                "Content-Type": "application/json",
+            },
+            timeout=timeout,
+        )
+
+        # Background flush thread
+        self._running = False
+        self._flush_thread: Optional[threading.Thread] = None
+        if auto_flush:
+            self._start_flush_thread()
+
+    def send_run(self, run: RunData) -> dict:
+        """Send a complete run synchronously to the backend."""
+        try:
+            payload = run.to_dict()
+            response = self._client.post(
+                "/api/v1/ingest/traces",
+                json=payload,
+            )
+            response.raise_for_status()
+            result = response.json()
+            logger.info(
+                f"Trace sent: run_id={result.get('run_id')}, "
+                f"spans={result.get('spans_ingested')}"
+            )
+            return result
+        except httpx.HTTPStatusError as e:
+            logger.error(f"Failed to send trace: {e.response.status_code} {e.response.text}")
+            raise
+        except Exception as e:
+            logger.error(f"Failed to send trace: {e}")
+            raise
+
+    def queue_run(self, run: RunData):
+        """Queue a run for batch sending."""
+        with self._lock:
+            self._queue.append(run)
+            if len(self._queue) >= self.batch_size:
+                self._flush_batch()
+
+    def flush(self):
+        """Flush all queued runs."""
+        with self._lock:
+            self._flush_batch()
+
+    def _flush_batch(self):
+        """Send all queued runs (called under lock)."""
+        if not self._queue:
+            return
+
+        batch = list(self._queue)
+        self._queue.clear()
+
+        for run in batch:
+            try:
+                self.send_run(run)
+            except Exception as e:
+                logger.error(f"Failed to flush run {run.run_id}: {e}")
+
+    def _start_flush_thread(self):
+        """Start background thread for periodic flushing."""
+        self._running = True
+        self._flush_thread = threading.Thread(
+            target=self._flush_loop, daemon=True, name="acr-flush"
+        )
+        self._flush_thread.start()
+
+    def _flush_loop(self):
+        """Background flush loop."""
+        while self._running:
+            time.sleep(self.flush_interval)
+            try:
+                self.flush()
+            except Exception as e:
+                logger.error(f"Background flush error: {e}")
+
+    def close(self):
+        """Flush remaining data and close the client."""
+        self._running = False
+        self.flush()
+        self._client.close()
+
+    def health_check(self) -> dict:
+        """Check if the backend is healthy."""
+        response = self._client.get("/health")
+        response.raise_for_status()
+        return response.json()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

agentcontrolroom-0.1.0/src/agentcontrolroom/cost.py

@@ -0,0 +1,112 @@
+"""
+Token-to-cost calculator with pricing tables for popular LLM models.
+"""
+
+from typing import Optional
+from dataclasses import dataclass
+
+
+@dataclass
+class ModelPricing:
+    """Pricing per 1K tokens for a model."""
+    prompt_cost_per_1k: float
+    completion_cost_per_1k: float
+
+
+# ── Pricing Table (cost per 1K tokens in USD) ───────
+MODEL_PRICING: dict[str, ModelPricing] = {
+    # OpenAI
+    "gpt-4": ModelPricing(0.03, 0.06),
+    "gpt-4-turbo": ModelPricing(0.01, 0.03),
+    "gpt-4-turbo-preview": ModelPricing(0.01, 0.03),
+    "gpt-4o": ModelPricing(0.005, 0.015),
+    "gpt-4o-mini": ModelPricing(0.00015, 0.0006),
+    "gpt-3.5-turbo": ModelPricing(0.0005, 0.0015),
+    "gpt-3.5-turbo-16k": ModelPricing(0.003, 0.004),
+    # Anthropic
+    "claude-3-opus": ModelPricing(0.015, 0.075),
+    "claude-3-opus-20240229": ModelPricing(0.015, 0.075),
+    "claude-3-sonnet": ModelPricing(0.003, 0.015),
+    "claude-3-sonnet-20240229": ModelPricing(0.003, 0.015),
+    "claude-3-haiku": ModelPricing(0.00025, 0.00125),
+    "claude-3-haiku-20240307": ModelPricing(0.00025, 0.00125),
+    "claude-3.5-sonnet": ModelPricing(0.003, 0.015),
+    "claude-3.5-sonnet-20240620": ModelPricing(0.003, 0.015),
+    "claude-3.5-haiku": ModelPricing(0.001, 0.005),
+    # Google
+    "gemini-pro": ModelPricing(0.00025, 0.0005),
+    "gemini-1.5-pro": ModelPricing(0.00125, 0.005),
+    "gemini-1.5-flash": ModelPricing(0.000075, 0.0003),
+    "gemini-2.0-flash": ModelPricing(0.0001, 0.0004),
+    # Meta (via API providers)
+    "llama-3-70b": ModelPricing(0.00059, 0.00079),
+    "llama-3-8b": ModelPricing(0.00005, 0.00008),
+    "llama-3.1-405b": ModelPricing(0.003, 0.003),
+    # Mistral
+    "mistral-large": ModelPricing(0.004, 0.012),
+    "mistral-medium": ModelPricing(0.0027, 0.0081),
+    "mistral-small": ModelPricing(0.001, 0.003),
+    "mixtral-8x7b": ModelPricing(0.0007, 0.0007),
+}
+
+
+class CostCalculator:
+    """
+    Calculate the cost of LLM calls based on model and token usage.
+
+    Usage:
+        calc = CostCalculator()
+        cost = calc.calculate("gpt-4o", prompt_tokens=500, completion_tokens=200)
+        print(f"Cost: ${cost:.6f}")
+
+        # Add custom model pricing
+        calc.add_model("my-model", 0.001, 0.002)
+    """
+
+    def __init__(self):
+        self._pricing = dict(MODEL_PRICING)
+
+    def add_model(
+        self,
+        model_name: str,
+        prompt_cost_per_1k: float,
+        completion_cost_per_1k: float,
+    ):
+        """Add or update pricing for a model."""
+        self._pricing[model_name] = ModelPricing(
+            prompt_cost_per_1k, completion_cost_per_1k
+        )
+
+    def calculate(
+        self,
+        model: str,
+        prompt_tokens: int = 0,
+        completion_tokens: int = 0,
+    ) -> Optional[float]:
+        """
+        Calculate cost in USD for a given model and token usage.
+        Returns None if model pricing is not found.
+        """
+        pricing = self._pricing.get(model)
+        if pricing is None:
+            # Try partial match (e.g., "gpt-4o-2024-05-13" → "gpt-4o")
+            for key, val in self._pricing.items():
+                if model.startswith(key):
+                    pricing = val
+                    break
+
+        if pricing is None:
+            return None
+
+        prompt_cost = (prompt_tokens / 1000) * pricing.prompt_cost_per_1k
+        completion_cost = (completion_tokens / 1000) * pricing.completion_cost_per_1k
+        return prompt_cost + completion_cost
+
+    def get_pricing(self, model: str) -> Optional[ModelPricing]:
+        """Get pricing info for a model."""
+        return self._pricing.get(model)
+
+    @property
+    def supported_models(self) -> list[str]:
+        """List all models with known pricing."""
+        return sorted(self._pricing.keys())