caum 1.0.0__tar.gz

caum-1.0.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: caum
+Version: 1.0.0
+Summary: AI Agent Observability - Detect when your agent is wasting money
+Home-page: https://caum.systems
+Author: Andres Silva
+Author-email: Andres Silva <contact@caum.systems>
+License-Expression: MIT
+Project-URL: Homepage, https://caum.systems
+Project-URL: Documentation, https://caum.systems/docs
+Project-URL: Dashboard, https://caum.systems/dashboard
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# CAUM — AI Agent Observability
+
+Detect when your AI agent is wasting money. Zero semantic access.
+
+## Install
+
+```bash
+pip install caum
+```
+
+## Quick Start (5 lines)
+
+```python
+import caum
+
+caum.init("caum_live_your_api_key")
+caum.observe("session-1", tool="bash", content="pytest tests/")
+caum.observe("session-1", tool="edit", content="Fixed the bug")
+result = caum.end("session-1")
+print(f"Tier: {result['tier']}, Cost wasted: ${result['cost']}")
+```
+
+## Zero-Code Integration (Anthropic)
+
+```python
+import anthropic
+import caum
+
+caum.init("caum_live_your_api_key")
+client = caum.wrap_anthropic(anthropic.Anthropic())
+
+# Use client exactly as before — CAUM observes automatically
+response = client.messages.create(
+    model="claude-sonnet-4-20250514",
+    messages=[{"role": "user", "content": "Fix the auth bug"}],
+    tools=[...],
+)
+```
+
+## Zero-Code Integration (OpenAI)
+
+```python
+import openai
+import caum
+
+caum.init("caum_live_your_api_key")
+client = caum.wrap_openai(openai.OpenAI())
+
+# Use client exactly as before
+response = client.chat.completions.create(
+    model="gpt-5",
+    messages=[...],
+    tools=[...],
+)
+```
+
+## What CAUM Detects
+
+| Regime | Meaning | Your Agent Is... |
+|--------|---------|------------------|
+| EXPLORER | Healthy | Using diverse tools, making progress |
+| GRIND | Degraded | Repeating similar actions |
+| LOOP | Critical | Stuck in a repetitive cycle |
+| REASONING_LOOP | Critical | Thinking in circles, not acting |
+| STAGNATION | Critical | Same tool, same result, over and over |
+
+## How It Works
+
+CAUM observes the **structure** of your agent's behavior — which tools it uses, in what order, how often it repeats. It never reads your prompts, code, or data.
+
+When your agent enters a wasteful pattern (looping, stagnating, circular reasoning), CAUM detects it and alerts you. You decide what to do. CAUM never stops your agent.
+
+## Get Your API Key
+
+Sign up at [caum.systems/pilot](https://caum.systems/pilot/) — 14-day free trial, 1,000 steps included.
+
+## Links
+
+- Website: [caum.systems](https://caum.systems)
+- Dashboard: [caum.systems/dashboard](https://caum.systems/dashboard)
+- Docs: [caum.systems/docs](https://caum.systems/docs)

caum-1.0.0/README.md

@@ -0,0 +1,81 @@
+# CAUM — AI Agent Observability
+
+Detect when your AI agent is wasting money. Zero semantic access.
+
+## Install
+
+```bash
+pip install caum
+```
+
+## Quick Start (5 lines)
+
+```python
+import caum
+
+caum.init("caum_live_your_api_key")
+caum.observe("session-1", tool="bash", content="pytest tests/")
+caum.observe("session-1", tool="edit", content="Fixed the bug")
+result = caum.end("session-1")
+print(f"Tier: {result['tier']}, Cost wasted: ${result['cost']}")
+```
+
+## Zero-Code Integration (Anthropic)
+
+```python
+import anthropic
+import caum
+
+caum.init("caum_live_your_api_key")
+client = caum.wrap_anthropic(anthropic.Anthropic())
+
+# Use client exactly as before — CAUM observes automatically
+response = client.messages.create(
+    model="claude-sonnet-4-20250514",
+    messages=[{"role": "user", "content": "Fix the auth bug"}],
+    tools=[...],
+)
+```
+
+## Zero-Code Integration (OpenAI)
+
+```python
+import openai
+import caum
+
+caum.init("caum_live_your_api_key")
+client = caum.wrap_openai(openai.OpenAI())
+
+# Use client exactly as before
+response = client.chat.completions.create(
+    model="gpt-5",
+    messages=[...],
+    tools=[...],
+)
+```
+
+## What CAUM Detects
+
+| Regime | Meaning | Your Agent Is... |
+|--------|---------|------------------|
+| EXPLORER | Healthy | Using diverse tools, making progress |
+| GRIND | Degraded | Repeating similar actions |
+| LOOP | Critical | Stuck in a repetitive cycle |
+| REASONING_LOOP | Critical | Thinking in circles, not acting |
+| STAGNATION | Critical | Same tool, same result, over and over |
+
+## How It Works
+
+CAUM observes the **structure** of your agent's behavior — which tools it uses, in what order, how often it repeats. It never reads your prompts, code, or data.
+
+When your agent enters a wasteful pattern (looping, stagnating, circular reasoning), CAUM detects it and alerts you. You decide what to do. CAUM never stops your agent.
+
+## Get Your API Key
+
+Sign up at [caum.systems/pilot](https://caum.systems/pilot/) — 14-day free trial, 1,000 steps included.
+
+## Links
+
+- Website: [caum.systems](https://caum.systems)
+- Dashboard: [caum.systems/dashboard](https://caum.systems/dashboard)
+- Docs: [caum.systems/docs](https://caum.systems/docs)

caum-1.0.0/caum/__init__.py

@@ -0,0 +1,28 @@
+"""
+CAUM SDK — AI Agent Observability
+==================================
+Detect when your AI agent is wasting money. 5 lines to integrate.
+
+Quick start:
+    import caum
+    caum.init("caum_live_your_api_key")
+    caum.observe("my-session", tool="bash", content="pytest tests/")
+    caum.observe("my-session", tool="edit", content="Fixed bug on line 42")
+    result = caum.end("my-session")
+    print(result["tier"])  # T1-T5
+
+As a proxy (zero code changes):
+    caum watch --api-key caum_live_xxx --provider anthropic
+"""
+
+__version__ = "1.0.0"
+
+from .client import init, observe, end, get_status
+from .proxy import CaumProxy
+from .wrappers import wrap_anthropic, wrap_openai
+
+__all__ = [
+    "init", "observe", "end", "get_status",
+    "CaumProxy",
+    "wrap_anthropic", "wrap_openai",
+]

caum-1.0.0/caum/client.py

@@ -0,0 +1,131 @@
+"""
+CAUM Client — Core API client for observing AI agents.
+"""
+import json
+import logging
+import threading
+from typing import Optional
+
+import requests
+
+logger = logging.getLogger("caum")
+
+_API_URL = "https://caum-observation-production.up.railway.app"
+_API_KEY = None
+_TIMEOUT = 10
+
+
+def init(api_key: str, api_url: Optional[str] = None):
+    """Initialize CAUM with your API key.
+
+    Args:
+        api_key: Your CAUM API key (starts with caum_live_)
+        api_url: Optional custom API URL (for self-hosted)
+    """
+    global _API_KEY, _API_URL
+    _API_KEY = api_key
+    if api_url:
+        _API_URL = api_url.rstrip("/")
+    logger.info(f"CAUM initialized (endpoint: {_API_URL})")
+
+
+def _post(path: str, data: dict) -> dict:
+    """Make authenticated POST request to CAUM API."""
+    if not _API_KEY:
+        raise RuntimeError("CAUM not initialized. Call caum.init('your_api_key') first.")
+    try:
+        resp = requests.post(
+            f"{_API_URL}{path}",
+            json=data,
+            headers={
+                "Authorization": f"Bearer {_API_KEY}",
+                "Content-Type": "application/json",
+            },
+            timeout=_TIMEOUT,
+        )
+        resp.raise_for_status()
+        return resp.json()
+    except requests.exceptions.RequestException as e:
+        logger.warning(f"CAUM API error: {e}")
+        return {"error": str(e)}
+
+
+def _post_async(path: str, data: dict):
+    """Non-blocking POST. Fire and forget — never slows down the agent."""
+    thread = threading.Thread(target=_post, args=(path, data), daemon=True)
+    thread.start()
+
+
+def observe(session_id: str, tool: str, content: str = "",
+            step: Optional[int] = None, agent_name: Optional[str] = None,
+            task: Optional[str] = None, cost_usd: float = 0.0,
+            blocking: bool = False) -> Optional[dict]:
+    """Observe a single tool call from your AI agent.
+
+    This is the core function. Call it every time your agent uses a tool.
+    By default it's non-blocking (fire-and-forget) so it never slows your agent.
+
+    Args:
+        session_id: Unique ID for this agent session
+        tool: Tool name (bash, edit, read, reasoning, etc.)
+        content: What the tool did (optional, CAUM doesn't read semantics)
+        step: Step number (auto-incremented if not provided)
+        agent_name: Name of the agent (optional)
+        task: Task description (optional)
+        cost_usd: Cost of this step in USD (optional)
+        blocking: If True, wait for response. If False (default), fire-and-forget.
+
+    Returns:
+        If blocking=True: dict with regime, failure_risk, tier, etc.
+        If blocking=False: None (result sent async)
+    """
+    data = {
+        "session_id": session_id,
+        "tool": tool,
+        "content": content[:500] if content else "",
+        "cost_usd": cost_usd,
+    }
+    if step is not None:
+        data["step"] = step
+    if agent_name:
+        data["agent_name"] = agent_name
+    if task:
+        data["task"] = task
+
+    if blocking:
+        return _post("/v1/step", data)
+    else:
+        _post_async("/v1/step", data)
+        return None
+
+
+def end(session_id: str, resolved: Optional[bool] = None) -> dict:
+    """End a session and get the final assessment.
+
+    Args:
+        session_id: The session to finalize
+        resolved: Did the agent succeed? True/False/None (auto-infer)
+
+    Returns:
+        dict with uds, tier, regime, cost, etc.
+    """
+    data = {}
+    if resolved is not None:
+        data["resolved"] = resolved
+    return _post(f"/v1/session/{session_id}/end", data)
+
+
+def get_status() -> dict:
+    """Get your CAUM usage and calibration status."""
+    if not _API_KEY:
+        raise RuntimeError("CAUM not initialized.")
+    try:
+        resp = requests.get(
+            f"{_API_URL}/v1/usage",
+            headers={"Authorization": f"Bearer {_API_KEY}"},
+            timeout=_TIMEOUT,
+        )
+        resp.raise_for_status()
+        return resp.json()
+    except requests.exceptions.RequestException as e:
+        return {"error": str(e)}

caum-1.0.0/caum/proxy.py

@@ -0,0 +1,48 @@
+"""
+CAUM Proxy — Sits between your agent and the LLM API.
+Zero code changes required.
+
+Usage:
+    from caum_sdk import CaumProxy
+    proxy = CaumProxy(api_key="caum_live_xxx", provider="anthropic")
+    proxy.start(port=8080)
+
+    # Point your agent's API base URL to http://localhost:8080
+    # CAUM intercepts, observes, and forwards to the real API
+"""
+import logging
+
+logger = logging.getLogger("caum.proxy")
+
+
+class CaumProxy:
+    """HTTP proxy that intercepts LLM API calls and observes tool usage.
+
+    This is a placeholder for the full proxy implementation.
+    The proxy will:
+    1. Listen on a local port
+    2. Intercept POST requests to /v1/messages (Anthropic) or /v1/chat/completions (OpenAI)
+    3. Forward to the real API
+    4. Parse the response for tool_use blocks
+    5. Send observations to CAUM API (non-blocking)
+    6. Return the original response unchanged
+
+    The agent sees no difference. CAUM observes everything.
+    """
+
+    def __init__(self, api_key: str, provider: str = "anthropic",
+                 caum_api_url: str = None):
+        self.api_key = api_key
+        self.provider = provider
+        self.caum_api_url = caum_api_url
+        from . import client
+        client.init(api_key, caum_api_url)
+
+    def start(self, port: int = 8080):
+        """Start the proxy server."""
+        logger.info(f"CAUM proxy starting on port {port} (provider: {self.provider})")
+        logger.info("Point your agent's API base URL to http://localhost:{port}")
+        # TODO: implement with httpx or aiohttp reverse proxy
+        raise NotImplementedError(
+            "Full proxy coming soon. Use caum.wrap_anthropic() or caum.wrap_openai() instead."
+        )

caum-1.0.0/caum/wrappers.py

@@ -0,0 +1,211 @@
+"""
+CAUM Wrappers — Zero-code integration for Anthropic and OpenAI.
+
+Usage:
+    import anthropic
+    import caum
+
+    caum.init("caum_live_xxx")
+    client = caum.wrap_anthropic(anthropic.Anthropic())
+
+    # Use client exactly as before — CAUM observes automatically
+    response = client.messages.create(
+        model="claude-sonnet-4-20250514",
+        messages=[{"role": "user", "content": "Fix the bug in auth.py"}],
+        tools=[...],
+    )
+"""
+import json
+import logging
+import uuid
+from typing import Optional
+
+from . import client as caum_client
+
+logger = logging.getLogger("caum.wrapper")
+
+_step_counters = {}  # session_id -> step count
+
+
+def _next_step(session_id: str) -> int:
+    _step_counters[session_id] = _step_counters.get(session_id, 0) + 1
+    return _step_counters[session_id]
+
+
+def _extract_tool_calls_anthropic(response) -> list:
+    """Extract tool calls from an Anthropic response."""
+    tools = []
+    try:
+        for block in response.content:
+            if block.type == "tool_use":
+                tools.append({
+                    "tool": block.name,
+                    "content": json.dumps(block.input)[:500] if block.input else "",
+                    "id": block.id,
+                })
+            elif block.type == "text" and block.text:
+                tools.append({
+                    "tool": "reasoning",
+                    "content": block.text[:500],
+                })
+    except Exception as e:
+        logger.debug(f"Error extracting Anthropic tools: {e}")
+    return tools
+
+
+def _extract_tool_calls_openai(response) -> list:
+    """Extract tool calls from an OpenAI response."""
+    tools = []
+    try:
+        msg = response.choices[0].message
+        if msg.tool_calls:
+            for tc in msg.tool_calls:
+                tools.append({
+                    "tool": tc.function.name,
+                    "content": tc.function.arguments[:500] if tc.function.arguments else "",
+                    "id": tc.id,
+                })
+        if msg.content:
+            tools.append({
+                "tool": "reasoning",
+                "content": msg.content[:500],
+            })
+    except Exception as e:
+        logger.debug(f"Error extracting OpenAI tools: {e}")
+    return tools
+
+
+class _AnthropicMessagesWrapper:
+    """Wraps anthropic.Anthropic().messages to auto-observe tool calls."""
+
+    def __init__(self, original_messages, session_id: Optional[str] = None):
+        self._original = original_messages
+        self._session_id = session_id or f"caum-{uuid.uuid4().hex[:12]}"
+
+    def create(self, **kwargs):
+        response = self._original.create(**kwargs)
+
+        # Extract and observe tool calls
+        tool_calls = _extract_tool_calls_anthropic(response)
+        for tc in tool_calls:
+            caum_client.observe(
+                session_id=self._session_id,
+                tool=tc["tool"],
+                content=tc["content"],
+                step=_next_step(self._session_id),
+            )
+
+        # Estimate cost from usage
+        if hasattr(response, "usage"):
+            input_tokens = getattr(response.usage, "input_tokens", 0)
+            output_tokens = getattr(response.usage, "output_tokens", 0)
+            # Rough cost estimate (Claude Sonnet pricing)
+            cost = (input_tokens * 3 + output_tokens * 15) / 1_000_000
+            if cost > 0 and tool_calls:
+                tool_calls[-1]["cost_usd"] = cost
+
+        return response
+
+    def __getattr__(self, name):
+        return getattr(self._original, name)
+
+
+class _AnthropicWrapper:
+    """Wraps anthropic.Anthropic() client."""
+
+    def __init__(self, original_client, session_id: Optional[str] = None):
+        self._original = original_client
+        self._session_id = session_id
+        self.messages = _AnthropicMessagesWrapper(
+            original_client.messages, session_id)
+
+    def __getattr__(self, name):
+        if name == "messages":
+            return self.messages
+        return getattr(self._original, name)
+
+
+class _OpenAIChatCompletionsWrapper:
+    """Wraps openai.OpenAI().chat.completions to auto-observe."""
+
+    def __init__(self, original_completions, session_id: Optional[str] = None):
+        self._original = original_completions
+        self._session_id = session_id or f"caum-{uuid.uuid4().hex[:12]}"
+
+    def create(self, **kwargs):
+        response = self._original.create(**kwargs)
+
+        tool_calls = _extract_tool_calls_openai(response)
+        for tc in tool_calls:
+            caum_client.observe(
+                session_id=self._session_id,
+                tool=tc["tool"],
+                content=tc["content"],
+                step=_next_step(self._session_id),
+            )
+
+        return response
+
+    def __getattr__(self, name):
+        return getattr(self._original, name)
+
+
+class _OpenAIChatWrapper:
+    def __init__(self, original_chat, session_id):
+        self._original = original_chat
+        self.completions = _OpenAIChatCompletionsWrapper(
+            original_chat.completions, session_id)
+
+    def __getattr__(self, name):
+        if name == "completions":
+            return self.completions
+        return getattr(self._original, name)
+
+
+class _OpenAIWrapper:
+    def __init__(self, original_client, session_id):
+        self._original = original_client
+        self.chat = _OpenAIChatWrapper(original_client.chat, session_id)
+
+    def __getattr__(self, name):
+        if name == "chat":
+            return self.chat
+        return getattr(self._original, name)
+
+
+def wrap_anthropic(client, session_id: Optional[str] = None):
+    """Wrap an Anthropic client to auto-observe all tool calls.
+
+    Args:
+        client: An anthropic.Anthropic() instance
+        session_id: Optional session ID (auto-generated if not provided)
+
+    Returns:
+        Wrapped client — use exactly like the original
+
+    Example:
+        import anthropic, caum
+        caum.init("caum_live_xxx")
+        client = caum.wrap_anthropic(anthropic.Anthropic())
+        response = client.messages.create(...)  # CAUM observes automatically
+    """
+    return _AnthropicWrapper(client, session_id)
+
+
+def wrap_openai(client, session_id: Optional[str] = None):
+    """Wrap an OpenAI client to auto-observe all tool calls.
+
+    Args:
+        client: An openai.OpenAI() instance
+        session_id: Optional session ID (auto-generated if not provided)
+
+    Returns:
+        Wrapped client — use exactly like the original
+
+    Example:
+        import openai, caum
+        caum.init("caum_live_xxx")
+        client = caum.wrap_openai(openai.OpenAI())
+        response = client.chat.completions.create(...)  # CAUM observes automatically
+    """
+    return _OpenAIWrapper(client, session_id)

caum-1.0.0/caum.egg-info/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: caum
+Version: 1.0.0
+Summary: AI Agent Observability - Detect when your agent is wasting money
+Home-page: https://caum.systems
+Author: Andres Silva
+Author-email: Andres Silva <contact@caum.systems>
+License-Expression: MIT
+Project-URL: Homepage, https://caum.systems
+Project-URL: Documentation, https://caum.systems/docs
+Project-URL: Dashboard, https://caum.systems/dashboard
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# CAUM — AI Agent Observability
+
+Detect when your AI agent is wasting money. Zero semantic access.
+
+## Install
+
+```bash
+pip install caum
+```
+
+## Quick Start (5 lines)
+
+```python
+import caum
+
+caum.init("caum_live_your_api_key")
+caum.observe("session-1", tool="bash", content="pytest tests/")
+caum.observe("session-1", tool="edit", content="Fixed the bug")
+result = caum.end("session-1")
+print(f"Tier: {result['tier']}, Cost wasted: ${result['cost']}")
+```
+
+## Zero-Code Integration (Anthropic)
+
+```python
+import anthropic
+import caum
+
+caum.init("caum_live_your_api_key")
+client = caum.wrap_anthropic(anthropic.Anthropic())
+
+# Use client exactly as before — CAUM observes automatically
+response = client.messages.create(
+    model="claude-sonnet-4-20250514",
+    messages=[{"role": "user", "content": "Fix the auth bug"}],
+    tools=[...],
+)
+```
+
+## Zero-Code Integration (OpenAI)
+
+```python
+import openai
+import caum
+
+caum.init("caum_live_your_api_key")
+client = caum.wrap_openai(openai.OpenAI())
+
+# Use client exactly as before
+response = client.chat.completions.create(
+    model="gpt-5",
+    messages=[...],
+    tools=[...],
+)
+```
+
+## What CAUM Detects
+
+| Regime | Meaning | Your Agent Is... |
+|--------|---------|------------------|
+| EXPLORER | Healthy | Using diverse tools, making progress |
+| GRIND | Degraded | Repeating similar actions |
+| LOOP | Critical | Stuck in a repetitive cycle |
+| REASONING_LOOP | Critical | Thinking in circles, not acting |
+| STAGNATION | Critical | Same tool, same result, over and over |
+
+## How It Works
+
+CAUM observes the **structure** of your agent's behavior — which tools it uses, in what order, how often it repeats. It never reads your prompts, code, or data.
+
+When your agent enters a wasteful pattern (looping, stagnating, circular reasoning), CAUM detects it and alerts you. You decide what to do. CAUM never stops your agent.
+
+## Get Your API Key
+
+Sign up at [caum.systems/pilot](https://caum.systems/pilot/) — 14-day free trial, 1,000 steps included.
+
+## Links
+
+- Website: [caum.systems](https://caum.systems)
+- Dashboard: [caum.systems/dashboard](https://caum.systems/dashboard)
+- Docs: [caum.systems/docs](https://caum.systems/docs)