avenza 1.0.0__tar.gz

avenza-1.0.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: avenza
+Version: 1.0.0
+Summary: Instrument AI agents in one line. Cost, value, and SLO tracking, automatically.
+Author-email: Finacc Support and Solutions <noreply@avenza.app>
+License: MIT
+Project-URL: Homepage, https://avenza.app
+Project-URL: Documentation, https://avenza.app/docs
+Project-URL: Repository, https://github.com/bnyamesa/avenza
+Project-URL: Bug Tracker, https://github.com/bnyamesa/avenza/issues
+Keywords: ai,agents,llm,observability,cost-tracking,slo
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1; extra == "langchain"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: responses>=0.25; extra == "dev"
+Requires-Dist: anthropic>=0.25; extra == "dev"
+Requires-Dist: openai>=1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+
+# Avenza Python SDK
+
+Instrument AI agents in one line. Cost, value, and SLO tracking — automatically.
+
+## Install
+
+```bash
+pip install avenza
+```
+
+## Quickstart (3 lines)
+
+```python
+from avenza import Agent
+
+agent = Agent(name='Invoice Bot', risk_tier='T2')
+
+with agent.run() as run:
+    result = process_invoice(data)
+    run.success = result.is_valid
+    run.log_value('task_completed', quantity=1, unit_value_usd=1.50)
+```
+
+That's it. If you're using the official Anthropic, OpenAI, or Gemini client, token usage is captured automatically with zero additional code.
+
+## Setup wizard
+
+```bash
+avenza init
+```
+
+Interactive wizard that verifies your API key and writes a working starter script — not a docs page to interpret.
+
+## Diagnose
+
+```bash
+avenza doctor
+```
+
+Self-diagnose connection issues, missing instrumentation, and proxy configuration.
+
+## Auto-instrumentation
+
+The SDK patches the official provider clients the moment it's imported:
+
+```python
+import anthropic
+from avenza import Agent
+
+agent = Agent(name='Support Bot')
+client = anthropic.Anthropic()
+
+with agent.run() as run:
+    # Token usage captured automatically from this call
+    response = client.messages.create(model='claude-sonnet-4-6', ...)
+    run.success = True
+```
+
+Works across threads and `async`/`await` via Python's `contextvars`.
+
+## Manual token fallback
+
+```python
+with agent.run() as run:
+    response = my_llm_client.call(...)
+    run.set_tokens(response.input_tokens, response.output_tokens)
+    run.success = True
+```
+
+## LangChain
+
+```python
+from avenza.integrations.langchain import AvenzaCallbackHandler
+from langchain_anthropic import ChatAnthropic
+
+handler = AvenzaCallbackHandler(agent_name='Support Classifier', risk_tier='T1')
+llm = ChatAnthropic(model='claude-sonnet-4-6', callbacks=[handler])
+response = llm.invoke('Classify this ticket: ...')
+```
+
+## Testing
+
+```python
+from avenza.testing import MockAgent
+
+def test_my_agent():
+    agent = MockAgent(name='Invoice Bot')
+    with agent.run() as run:
+        run.success = True
+        run.log_value('task_completed', quantity=1, unit_value_usd=1.50)
+
+    assert agent.runs[-1].success is True
+    assert agent.runs[-1].value_events[0]['quantity'] == 1
+```
+
+## Configuration
+
+| Parameter | Default | Description |
+|---|---|---|
+| `name` | required | Agent display name |
+| `risk_tier` | `'T1'` | T1 (autonomous), T2 (approve-first), T3 (assist-only) |
+| `api_key` | `AVENZA_API_KEY` env | Bearer token from Settings → API Tokens |
+| `model` | None | LLM model for cost lookup (auto-detected when using auto-instrumentation) |
+| `auto_instrument` | `True` | Patch provider clients automatically |
+| `offline_buffer` | `True` | Queue failed sends to disk and retry |
+| `base_url` | `https://app.avenza.app` | Override for self-hosted |
+
+## Never blocks. Never raises.
+
+Every network call is fire-and-forget on a background thread. Avenza being down, slow, or returning errors will never crash your agent or add latency to your agent's actual work. Failed sends are buffered to `.avenza_buffer.jsonl` and retried on next startup.

avenza-1.0.0/README.md

@@ -0,0 +1,110 @@
+# Avenza Python SDK
+
+Instrument AI agents in one line. Cost, value, and SLO tracking — automatically.
+
+## Install
+
+```bash
+pip install avenza
+```
+
+## Quickstart (3 lines)
+
+```python
+from avenza import Agent
+
+agent = Agent(name='Invoice Bot', risk_tier='T2')
+
+with agent.run() as run:
+    result = process_invoice(data)
+    run.success = result.is_valid
+    run.log_value('task_completed', quantity=1, unit_value_usd=1.50)
+```
+
+That's it. If you're using the official Anthropic, OpenAI, or Gemini client, token usage is captured automatically with zero additional code.
+
+## Setup wizard
+
+```bash
+avenza init
+```
+
+Interactive wizard that verifies your API key and writes a working starter script — not a docs page to interpret.
+
+## Diagnose
+
+```bash
+avenza doctor
+```
+
+Self-diagnose connection issues, missing instrumentation, and proxy configuration.
+
+## Auto-instrumentation
+
+The SDK patches the official provider clients the moment it's imported:
+
+```python
+import anthropic
+from avenza import Agent
+
+agent = Agent(name='Support Bot')
+client = anthropic.Anthropic()
+
+with agent.run() as run:
+    # Token usage captured automatically from this call
+    response = client.messages.create(model='claude-sonnet-4-6', ...)
+    run.success = True
+```
+
+Works across threads and `async`/`await` via Python's `contextvars`.
+
+## Manual token fallback
+
+```python
+with agent.run() as run:
+    response = my_llm_client.call(...)
+    run.set_tokens(response.input_tokens, response.output_tokens)
+    run.success = True
+```
+
+## LangChain
+
+```python
+from avenza.integrations.langchain import AvenzaCallbackHandler
+from langchain_anthropic import ChatAnthropic
+
+handler = AvenzaCallbackHandler(agent_name='Support Classifier', risk_tier='T1')
+llm = ChatAnthropic(model='claude-sonnet-4-6', callbacks=[handler])
+response = llm.invoke('Classify this ticket: ...')
+```
+
+## Testing
+
+```python
+from avenza.testing import MockAgent
+
+def test_my_agent():
+    agent = MockAgent(name='Invoice Bot')
+    with agent.run() as run:
+        run.success = True
+        run.log_value('task_completed', quantity=1, unit_value_usd=1.50)
+
+    assert agent.runs[-1].success is True
+    assert agent.runs[-1].value_events[0]['quantity'] == 1
+```
+
+## Configuration
+
+| Parameter | Default | Description |
+|---|---|---|
+| `name` | required | Agent display name |
+| `risk_tier` | `'T1'` | T1 (autonomous), T2 (approve-first), T3 (assist-only) |
+| `api_key` | `AVENZA_API_KEY` env | Bearer token from Settings → API Tokens |
+| `model` | None | LLM model for cost lookup (auto-detected when using auto-instrumentation) |
+| `auto_instrument` | `True` | Patch provider clients automatically |
+| `offline_buffer` | `True` | Queue failed sends to disk and retry |
+| `base_url` | `https://app.avenza.app` | Override for self-hosted |
+
+## Never blocks. Never raises.
+
+Every network call is fire-and-forget on a background thread. Avenza being down, slow, or returning errors will never crash your agent or add latency to your agent's actual work. Failed sends are buffered to `.avenza_buffer.jsonl` and retried on next startup.

avenza-1.0.0/avenza/__init__.py

@@ -0,0 +1,30 @@
+"""
+Avenza Python SDK
+
+Instrument AI agents in one line. Cost, value, and SLO tracking — automatically.
+
+Quickstart:
+    from avenza import Agent
+
+    agent = Agent(name='Invoice Bot', risk_tier='T2')
+
+    with agent.run() as run:
+        result = process(data)
+        run.success = result.ok
+        run.log_value('task_completed', quantity=1, unit_value_usd=1.50)
+
+Auto-instrumentation is active by default — if you're using the official Anthropic,
+OpenAI, or Gemini client, token usage is captured without any additional code.
+"""
+from __future__ import annotations
+
+from .agent import Agent
+from .exceptions import AvenzaConfigError, AvenzaError
+
+try:
+    from importlib.metadata import version as _version
+    __version__: str = _version("avenza")
+except Exception:
+    __version__ = "dev"
+
+__all__ = ["Agent", "AvenzaError", "AvenzaConfigError", "__version__"]

avenza-1.0.0/avenza/_buffer.py

@@ -0,0 +1,52 @@
+"""
+Offline buffer — persists failed sends to .avenza_buffer.jsonl and retries
+on next SDK init. Designed for intermittent-connectivity environments.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .client import AvenzaClient
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_PATH = ".avenza_buffer.jsonl"
+
+
+class OfflineBuffer:
+    def __init__(self, path: str = _DEFAULT_PATH) -> None:
+        self._path = path
+
+    def save(self, path: str, payload: dict[str, Any]) -> None:
+        try:
+            with open(self._path, "a", encoding="utf-8") as f:
+                f.write(json.dumps({"path": path, "payload": payload}) + "\n")
+        except OSError:
+            pass  # Read-only FS or permission error — drop silently
+
+    def flush(self, client: "AvenzaClient") -> None:
+        if not os.path.exists(self._path):
+            return
+        try:
+            with open(self._path, encoding="utf-8") as f:
+                lines = f.readlines()
+            os.remove(self._path)
+        except OSError:
+            return
+
+        flushed = 0
+        for line in lines:
+            try:
+                entry = json.loads(line.strip())
+                if entry.get("path") and entry.get("payload") is not None:
+                    client.post_async(entry["path"], entry["payload"])
+                    flushed += 1
+            except (json.JSONDecodeError, KeyError):
+                pass
+
+        if flushed:
+            logger.info("avenza: flushed %d buffered run(s) from offline buffer", flushed)

avenza-1.0.0/avenza/_context.py

@@ -0,0 +1,30 @@
+"""
+contextvars-based active-run tracking.
+
+Each OS thread and each asyncio task gets its own isolated view of the current
+run, so token capture is always attributed to the correct run even under
+concurrent async tasks or multi-threaded agents.
+"""
+from __future__ import annotations
+
+import contextvars
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from .run import RunContext
+
+_current_run: contextvars.ContextVar[Optional["RunContext"]] = contextvars.ContextVar(
+    "avenza_current_run", default=None
+)
+
+
+def get_current_run() -> Optional["RunContext"]:
+    return _current_run.get()
+
+
+def set_current_run(run: "RunContext") -> contextvars.Token:
+    return _current_run.set(run)
+
+
+def reset_current_run(token: contextvars.Token) -> None:
+    _current_run.reset(token)

avenza-1.0.0/avenza/_instrument/__init__.py

@@ -0,0 +1,17 @@
+"""
+Auto-instrumentation dispatcher.
+
+patch_all() tries each provider's patch. If the provider's SDK is not
+installed, the patch is silently skipped — no error, no warning.
+"""
+from __future__ import annotations
+
+
+def patch_all() -> None:
+    from .anthropic_patch import patch_anthropic
+    from .openai_patch import patch_openai
+    from .gemini_patch import patch_gemini
+
+    patch_anthropic()
+    patch_openai()
+    patch_gemini()

avenza-1.0.0/avenza/_instrument/anthropic_patch.py

@@ -0,0 +1,77 @@
+"""
+Patches Anthropic's official Python client to capture token usage automatically.
+Wraps both the sync and async message creation methods.
+"""
+from __future__ import annotations
+
+import functools
+import logging
+
+from .._context import get_current_run
+
+logger = logging.getLogger(__name__)
+
+_patched = False
+
+
+def patch_anthropic() -> None:
+    global _patched
+    if _patched:
+        return
+
+    try:
+        import anthropic
+    except ImportError:
+        return  # SDK not installed — nothing to patch, no error
+
+    try:
+        _patch_sync(anthropic)
+        _patch_async(anthropic)
+        _patched = True
+        logger.debug("avenza: anthropic auto-instrumentation active")
+    except Exception as exc:
+        logger.debug("avenza: anthropic patch failed (non-fatal) — %s", exc)
+
+
+def _patch_sync(anthropic: object) -> None:
+    messages_cls = anthropic.resources.messages.Messages  # type: ignore[attr-defined]
+    original = messages_cls.create
+
+    @functools.wraps(original)
+    def wrapped(self: object, *args: object, **kwargs: object) -> object:
+        response = original(self, *args, **kwargs)
+        run = get_current_run()
+        if run is not None and hasattr(response, "usage"):
+            run._record_auto_tokens(
+                provider="anthropic",
+                model=str(kwargs.get("model", "unknown")),
+                input_tokens=getattr(response.usage, "input_tokens", 0),
+                output_tokens=getattr(response.usage, "output_tokens", 0),
+            )
+        return response
+
+    messages_cls.create = wrapped
+
+
+def _patch_async(anthropic: object) -> None:
+    try:
+        async_cls = anthropic.resources.messages.AsyncMessages  # type: ignore[attr-defined]
+    except AttributeError:
+        return  # older version — no async client
+
+    original_async = async_cls.create
+
+    @functools.wraps(original_async)
+    async def wrapped_async(self: object, *args: object, **kwargs: object) -> object:
+        response = await original_async(self, *args, **kwargs)
+        run = get_current_run()
+        if run is not None and hasattr(response, "usage"):
+            run._record_auto_tokens(
+                provider="anthropic",
+                model=str(kwargs.get("model", "unknown")),
+                input_tokens=getattr(response.usage, "input_tokens", 0),
+                output_tokens=getattr(response.usage, "output_tokens", 0),
+            )
+        return response
+
+    async_cls.create = wrapped_async

avenza-1.0.0/avenza/_instrument/gemini_patch.py

@@ -0,0 +1,76 @@
+"""
+Patches Google's Generative AI client to capture token usage automatically.
+Works with both google-generativeai (genai) and google-cloud-aiplatform clients.
+"""
+from __future__ import annotations
+
+import functools
+import logging
+
+from .._context import get_current_run
+
+logger = logging.getLogger(__name__)
+
+_patched = False
+
+
+def patch_gemini() -> None:
+    global _patched
+    if _patched:
+        return
+
+    try:
+        _patch_genai()
+        _patched = True
+    except ImportError:
+        pass  # Neither SDK installed — skip silently
+    except Exception as exc:
+        logger.debug("avenza: gemini patch failed (non-fatal) — %s", exc)
+
+
+def _patch_genai() -> None:
+    import google.generativeai as genai  # type: ignore[import]
+    model_cls = genai.GenerativeModel
+
+    original_sync = model_cls.generate_content
+
+    @functools.wraps(original_sync)
+    def wrapped_sync(self: object, *args: object, **kwargs: object) -> object:
+        response = original_sync(self, *args, **kwargs)
+        run = get_current_run()
+        if run is not None:
+            _capture_gemini_usage(run, response, getattr(self, "model_name", "gemini"))
+        return response
+
+    model_cls.generate_content = wrapped_sync
+    logger.debug("avenza: gemini (google-generativeai) auto-instrumentation active")
+
+    # Async variant
+    if hasattr(model_cls, "generate_content_async"):
+        original_async = model_cls.generate_content_async
+
+        @functools.wraps(original_async)
+        async def wrapped_async(self: object, *args: object, **kwargs: object) -> object:
+            response = await original_async(self, *args, **kwargs)
+            run = get_current_run()
+            if run is not None:
+                _capture_gemini_usage(run, response, getattr(self, "model_name", "gemini"))
+            return response
+
+        model_cls.generate_content_async = wrapped_async
+
+
+def _capture_gemini_usage(run: object, response: object, model_name: str) -> None:
+    # google-generativeai stores token counts in response.usage_metadata
+    usage = getattr(response, "usage_metadata", None)
+    if usage is None:
+        return
+    input_tokens  = getattr(usage, "prompt_token_count", 0) or 0
+    output_tokens = getattr(usage, "candidates_token_count", 0) or 0
+    if input_tokens or output_tokens:
+        run._record_auto_tokens(  # type: ignore[union-attr]
+            provider="google",
+            model=model_name,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+        )

avenza-1.0.0/avenza/_instrument/openai_patch.py

@@ -0,0 +1,77 @@
+"""
+Patches OpenAI's official Python client to capture token usage automatically.
+Handles both sync (Completions.create) and async (AsyncCompletions.create).
+"""
+from __future__ import annotations
+
+import functools
+import logging
+
+from .._context import get_current_run
+
+logger = logging.getLogger(__name__)
+
+_patched = False
+
+
+def patch_openai() -> None:
+    global _patched
+    if _patched:
+        return
+
+    try:
+        import openai
+    except ImportError:
+        return
+
+    try:
+        _patch_sync(openai)
+        _patch_async(openai)
+        _patched = True
+        logger.debug("avenza: openai auto-instrumentation active")
+    except Exception as exc:
+        logger.debug("avenza: openai patch failed (non-fatal) — %s", exc)
+
+
+def _patch_sync(openai: object) -> None:
+    completions_cls = openai.resources.chat.completions.Completions  # type: ignore[attr-defined]
+    original = completions_cls.create
+
+    @functools.wraps(original)
+    def wrapped(self: object, *args: object, **kwargs: object) -> object:
+        response = original(self, *args, **kwargs)
+        run = get_current_run()
+        if run is not None and hasattr(response, "usage") and response.usage is not None:
+            run._record_auto_tokens(
+                provider="openai",
+                model=str(kwargs.get("model", getattr(response, "model", "unknown"))),
+                input_tokens=getattr(response.usage, "prompt_tokens", 0),
+                output_tokens=getattr(response.usage, "completion_tokens", 0),
+            )
+        return response
+
+    completions_cls.create = wrapped
+
+
+def _patch_async(openai: object) -> None:
+    try:
+        async_cls = openai.resources.chat.completions.AsyncCompletions  # type: ignore[attr-defined]
+    except AttributeError:
+        return
+
+    original_async = async_cls.create
+
+    @functools.wraps(original_async)
+    async def wrapped_async(self: object, *args: object, **kwargs: object) -> object:
+        response = await original_async(self, *args, **kwargs)
+        run = get_current_run()
+        if run is not None and hasattr(response, "usage") and response.usage is not None:
+            run._record_auto_tokens(
+                provider="openai",
+                model=str(kwargs.get("model", getattr(response, "model", "unknown"))),
+                input_tokens=getattr(response.usage, "prompt_tokens", 0),
+                output_tokens=getattr(response.usage, "completion_tokens", 0),
+            )
+        return response
+
+    async_cls.create = wrapped_async