maev-sdk 0.3.0__tar.gz

maev_sdk-0.3.0/.gitignore

@@ -0,0 +1,39 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+node_modules
+/.pnp
+.pnp.js
+.yarn/install-state.gz
+
+# testing
+/coverage
+
+# next.js
+.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+scripts/test_e2e.py
+scripts/seed-test-org.ts
+scripts/test_failing_agent.py

maev_sdk-0.3.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: maev-sdk
+Version: 0.3.0
+Summary: Maev AI Agent Observability SDK — one-liner instrumentation for AI agents
+Project-URL: Homepage, https://maev.dev
+Project-URL: Documentation, https://docs.maev.dev
+Project-URL: Repository, https://github.com/ujjwalpreenja1308-web/veil
+Author-email: Maev <eng@maev.dev>
+License-Expression: MIT
+Keywords: agents,ai,observability,telemetry
+Classifier: Development Status :: 3 - Alpha
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: openlit>=1.33.0
+Description-Content-Type: text/markdown
+
+# Maev Python SDK
+
+One-liner observability for AI agents.
+
+## Installation
+
+```bash
+pip install maev-sdk
+```
+
+## Quickstart
+
+```python
+import maev
+
+maev.init(api_key="vl_xxx")
+```
+
+That's it. Add this before your agent runs. Maev automatically instruments
+OpenAI, Anthropic, LangChain, LlamaIndex, and other popular LLM libraries,
+and sends all telemetry to your Maev dashboard.
+
+## Serverless functions (Lambda, Cloud Functions, Vercel, etc.)
+
+In long-running processes (servers, scripts, notebooks), Maev automatically
+sends all telemetry when the process exits. No extra code needed.
+
+In **serverless functions**, the process doesn't exit cleanly — it gets frozen
+or killed by the platform the moment your handler returns. Any telemetry still
+in the buffer is silently dropped, and your session never closes in the
+dashboard.
+
+Call `maev.flush()` at the end of your handler to force delivery before the
+freeze:
+
+```python
+import maev
+
+maev.init(api_key="vl_xxx", agent_name="My Lambda")
+
+def handler(event, context):
+    # ... your agent logic ...
+
+    maev.flush()  # send everything before Lambda freezes
+    return result
+```
+
+`flush()` does two things in order:
+1. Forces the OpenTelemetry exporter to drain any buffered spans (LLM call data)
+2. Sends a `session.end` event so Maev closes and classifies the session
+
+It is safe to call multiple times — only the first call does anything.
+
+**Environments where you must call `flush()`:**
+
+| Platform | Why |
+|---|---|
+| AWS Lambda | Handler returns → process frozen immediately |
+| Google Cloud Functions | Same — process suspended after return |
+| Vercel / Netlify Functions | Execution context torn down after response |
+| Azure Functions | Consumption plan freezes after invocation |
+
+**Environments where `flush()` is optional** (but harmless):
+
+- Long-running servers (FastAPI, Flask, Django)
+- CLI scripts
+- Jupyter notebooks
+- Docker containers
+
+## How it works
+
+- Telemetry is collected and sent asynchronously — zero impact on your agent's performance.
+- Sessions are automatically tracked from the first LLM call through to process exit.
+- Failures are detected and classified server-side — no configuration required.
+- Every failure triggers an alert in your Maev dashboard and via email.
+
+## Supported Libraries
+
+Maev auto-instruments all major LLM frameworks including:
+
+- OpenAI
+- Anthropic
+- LangChain
+- LlamaIndex
+- Cohere
+- Mistral
+- Google Gemini
+- AWS Bedrock
+- And more
+
+## Requirements
+
+- Python >= 3.9
+
+## Your API Key
+
+Find your API key in the [Maev Dashboard](https://home.maev.dev/dashboard/settings) under Settings.
+Keys follow the format `vl_` followed by 64 hex characters.
+
+## Self-hosting
+
+If you are running Maev on your own infrastructure, pass the `endpoint` parameter:
+
+```python
+maev.init(api_key="vl_xxx", endpoint="https://your-maev-instance.com")
+```

maev_sdk-0.3.0/README.md

@@ -0,0 +1,106 @@
+# Maev Python SDK
+
+One-liner observability for AI agents.
+
+## Installation
+
+```bash
+pip install maev-sdk
+```
+
+## Quickstart
+
+```python
+import maev
+
+maev.init(api_key="vl_xxx")
+```
+
+That's it. Add this before your agent runs. Maev automatically instruments
+OpenAI, Anthropic, LangChain, LlamaIndex, and other popular LLM libraries,
+and sends all telemetry to your Maev dashboard.
+
+## Serverless functions (Lambda, Cloud Functions, Vercel, etc.)
+
+In long-running processes (servers, scripts, notebooks), Maev automatically
+sends all telemetry when the process exits. No extra code needed.
+
+In **serverless functions**, the process doesn't exit cleanly — it gets frozen
+or killed by the platform the moment your handler returns. Any telemetry still
+in the buffer is silently dropped, and your session never closes in the
+dashboard.
+
+Call `maev.flush()` at the end of your handler to force delivery before the
+freeze:
+
+```python
+import maev
+
+maev.init(api_key="vl_xxx", agent_name="My Lambda")
+
+def handler(event, context):
+    # ... your agent logic ...
+
+    maev.flush()  # send everything before Lambda freezes
+    return result
+```
+
+`flush()` does two things in order:
+1. Forces the OpenTelemetry exporter to drain any buffered spans (LLM call data)
+2. Sends a `session.end` event so Maev closes and classifies the session
+
+It is safe to call multiple times — only the first call does anything.
+
+**Environments where you must call `flush()`:**
+
+| Platform | Why |
+|---|---|
+| AWS Lambda | Handler returns → process frozen immediately |
+| Google Cloud Functions | Same — process suspended after return |
+| Vercel / Netlify Functions | Execution context torn down after response |
+| Azure Functions | Consumption plan freezes after invocation |
+
+**Environments where `flush()` is optional** (but harmless):
+
+- Long-running servers (FastAPI, Flask, Django)
+- CLI scripts
+- Jupyter notebooks
+- Docker containers
+
+## How it works
+
+- Telemetry is collected and sent asynchronously — zero impact on your agent's performance.
+- Sessions are automatically tracked from the first LLM call through to process exit.
+- Failures are detected and classified server-side — no configuration required.
+- Every failure triggers an alert in your Maev dashboard and via email.
+
+## Supported Libraries
+
+Maev auto-instruments all major LLM frameworks including:
+
+- OpenAI
+- Anthropic
+- LangChain
+- LlamaIndex
+- Cohere
+- Mistral
+- Google Gemini
+- AWS Bedrock
+- And more
+
+## Requirements
+
+- Python >= 3.9
+
+## Your API Key
+
+Find your API key in the [Maev Dashboard](https://home.maev.dev/dashboard/settings) under Settings.
+Keys follow the format `vl_` followed by 64 hex characters.
+
+## Self-hosting
+
+If you are running Maev on your own infrastructure, pass the `endpoint` parameter:
+
+```python
+maev.init(api_key="vl_xxx", endpoint="https://your-maev-instance.com")
+```

maev_sdk-0.3.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "maev-sdk"
+version = "0.3.0"
+description = "Maev AI Agent Observability SDK — one-liner instrumentation for AI agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Maev", email = "eng@maev.dev" }]
+keywords = ["observability", "ai", "agents", "telemetry"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: System :: Monitoring",
+    "Typing :: Typed",
+]
+dependencies = [
+    "openlit>=1.33.0",
+]
+
+[project.urls]
+Homepage = "https://maev.dev"
+Documentation = "https://docs.maev.dev"
+Repository = "https://github.com/ujjwalpreenja1308-web/veil"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/maev"]

maev_sdk-0.3.0/src/maev/__init__.py

@@ -0,0 +1,377 @@
+"""Maev Python SDK - one-liner observability for AI agents.
+
+Usage::
+
+    import maev
+    maev.init(api_key="vl_xxx")
+
+    # Optional: name your agent so it shows up correctly in the dashboard
+    maev.init(api_key="vl_xxx", agent_name="Sales Agent")
+
+    # In serverless functions, call flush() before the handler returns
+    # to guarantee telemetry is delivered before the process is frozen.
+    maev.flush()
+
+That's it. Active Maev Fixes are automatically fetched and injected into
+every LLM call - no additional setup required.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import sys
+import threading
+import urllib.request
+import warnings
+from datetime import datetime, timezone
+from typing import List, Optional
+
+__all__ = ["init", "flush"]
+
+_initialized: bool = False
+_session_id: Optional[str] = None
+_api_key: Optional[str] = None
+_endpoint: Optional[str] = None
+_agent_name: Optional[str] = None
+_flushed: bool = False  # guard: flush sends session.end exactly once
+
+# Active corrective prompts fetched from the registry on init.
+# These are prepended to every LLM system prompt via the OpenLIT hook.
+_active_fixes: List[str] = []
+
+
+def init(
+    api_key: str,
+    *,
+    agent_name: str = "default",
+    endpoint: str = "https://maevhq.com",
+) -> None:
+    """Initialize the Maev SDK.
+
+    Parameters
+    ----------
+    api_key:
+        Your Maev API key (starts with ``vl_``).
+    agent_name:
+        Human-readable name for this agent. Shown in the Maev dashboard.
+        Defaults to ``"default"``. Use a descriptive name like ``"Sales Agent"``.
+    endpoint:
+        Override the ingest URL. Leave unset unless self-hosting.
+    """
+    global _initialized, _session_id, _api_key, _endpoint, _agent_name  # noqa: PLW0603
+
+    if _initialized:
+        warnings.warn(
+            "maev.init() already called. Ignoring duplicate.",
+            stacklevel=2,
+        )
+        return
+
+    if not api_key or not isinstance(api_key, str) or not api_key.startswith("vl_"):
+        raise ValueError(
+            "Invalid Maev API key - must start with 'vl_'. "
+            "Get your key from https://maevhq.com/dashboard/settings"
+        )
+
+    import uuid
+    _session_id = str(uuid.uuid4())
+    _api_key = api_key
+    _endpoint = endpoint.rstrip("/")
+    _agent_name = agent_name
+
+    # 1. Fetch active corrective prompts from the registry (background thread,
+    #    non-blocking - if it fails, agent runs without fixes, never crashes).
+    _fetch_active_fixes_async()
+
+    # 2. Start OpenLIT instrumentation with Maev as the OTLP backend.
+    _start(
+        api_key=api_key,
+        agent_name=agent_name,
+        endpoint=_endpoint,
+        session_id=_session_id,
+    )
+
+    # 3. Register the LLM pre-call hook to inject fixes into system prompts.
+    _register_fix_hook()
+
+    atexit.register(_shutdown)
+    _initialized = True
+
+
+def flush(timeout: float = 5.0) -> None:
+    """Flush all pending telemetry and close the current session.
+
+    Call this explicitly in serverless functions (AWS Lambda, Google Cloud
+    Functions, Vercel Edge, etc.) before your handler returns, because the
+    process may be frozen or killed before the ``atexit`` hook fires.
+
+    It is safe to call ``flush()`` multiple times - only the first call sends
+    the ``session.end`` event; subsequent calls are no-ops.
+
+    Parameters
+    ----------
+    timeout:
+        Seconds to wait for the HTTP request to complete. Default is 5.
+    """
+    global _flushed  # noqa: PLW0603
+
+    if not _initialized:
+        warnings.warn(
+            "maev.flush() called before maev.init() - nothing to flush.",
+            stacklevel=2,
+        )
+        return
+
+    if _flushed:
+        return
+
+    _flushed = True
+
+    # 1. Force OpenLIT's OTLP span exporter to flush buffered spans.
+    _flush_openlit()
+
+    # 2. Send session.end to close the session in Maev's pipeline.
+    _send_session_end(timeout=timeout)
+
+
+# --- Fix Registry -------------------------------------------------------------
+
+def _fetch_active_fixes_async() -> None:
+    """Fetch active corrective prompts in a background daemon thread.
+
+    Runs at init time. Never blocks. On any error, _active_fixes stays empty
+    and the agent runs normally without fixes.
+    """
+    t = threading.Thread(target=_fetch_active_fixes, daemon=True)
+    t.start()
+
+
+def _fetch_active_fixes() -> None:
+    """Synchronously fetch active fixes from the Maev registry."""
+    global _active_fixes  # noqa: PLW0603
+
+    if not _api_key or not _endpoint or not _agent_name:
+        return
+
+    try:
+        import urllib.parse
+        url = (
+            f"{_endpoint}/api/veil-fix/active"
+            f"?agent_name={urllib.parse.quote(_agent_name)}"
+        )
+        req = urllib.request.Request(
+            url,
+            headers={"x-api-key": _api_key},
+            method="GET",
+        )
+        with urllib.request.urlopen(req, timeout=3.0) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+            prompts = data.get("corrective_prompts", [])
+            if isinstance(prompts, list):
+                _active_fixes = [str(p) for p in prompts if p]
+                if _active_fixes:
+                    print(
+                        f"[maev] {len(_active_fixes)} active fix(es) loaded for agent '{_agent_name}'",
+                        file=sys.stderr,
+                    )
+    except Exception as exc:  # noqa: BLE001
+        # Non-fatal - agent runs without fixes
+        print(f"[maev] Could not fetch active fixes (non-fatal): {exc}", file=sys.stderr)
+
+
+def _build_fix_prefix() -> str:
+    """Build the corrective prompt prefix to prepend to any system prompt."""
+    if not _active_fixes:
+        return ""
+    joined = "\n".join(f"- {p}" for p in _active_fixes)
+    return f"[Maev Corrections - follow these instructions at all times]\n{joined}\n\n"
+
+
+# --- OpenLIT Hook -------------------------------------------------------------
+
+def _register_fix_hook() -> None:
+    """Register a pre-call hook into the OpenLIT-patched LLM clients.
+
+    OpenLIT monkey-patches openai.ChatCompletion.create (and equivalents) to
+    capture spans. We wrap the same call to prepend active fixes to the
+    system prompt - same interception point, zero extra setup for the engineer.
+
+    If no fixes are active, the hook is a no-op and adds zero overhead.
+    """
+    if not _active_fixes:
+        # No fixes - nothing to inject, skip hook registration entirely
+        return
+
+    _patch_openai()
+    _patch_anthropic()
+
+
+def _patch_openai() -> None:
+    """Prepend fixes to OpenAI chat completion system messages."""
+    try:
+        import openai  # type: ignore[import-untyped]
+    except ImportError:
+        return
+
+    prefix = _build_fix_prefix()
+    if not prefix:
+        return
+
+    # Patch the synchronous client
+    _wrap_openai_client(openai, prefix)
+
+    # Also patch the module-level create if used directly
+    try:
+        original_create = openai.chat.completions.create
+
+        def _patched_create(*args, **kwargs):  # type: ignore[no-untyped-def]
+            kwargs = _inject_system_prefix(kwargs, prefix)
+            return original_create(*args, **kwargs)
+
+        openai.chat.completions.create = _patched_create
+    except AttributeError:
+        pass
+
+
+def _wrap_openai_client(openai_module, prefix: str) -> None:  # type: ignore[no-untyped-def]
+    """Wrap OpenAI.Chat.Completions.create on the module-level client."""
+    try:
+        OriginalClient = openai_module.OpenAI
+
+        class PatchedOpenAI(OriginalClient):  # type: ignore[misc]
+            def __init__(self, *args, **kwargs):  # type: ignore[no-untyped-def]
+                super().__init__(*args, **kwargs)
+                orig = self.chat.completions.create
+
+                def _create(*a, **kw):  # type: ignore[no-untyped-def]
+                    kw = _inject_system_prefix(kw, prefix)
+                    return orig(*a, **kw)
+
+                self.chat.completions.create = _create  # type: ignore[method-assign]
+
+        openai_module.OpenAI = PatchedOpenAI
+    except (AttributeError, TypeError):
+        pass
+
+
+def _patch_anthropic() -> None:
+    """Prepend fixes to Anthropic Messages.create system prompts."""
+    try:
+        import anthropic  # type: ignore[import-untyped]
+    except ImportError:
+        return
+
+    prefix = _build_fix_prefix()
+    if not prefix:
+        return
+
+    try:
+        OriginalClient = anthropic.Anthropic
+
+        class PatchedAnthropic(OriginalClient):  # type: ignore[misc]
+            def __init__(self, *args, **kwargs):  # type: ignore[no-untyped-def]
+                super().__init__(*args, **kwargs)
+                orig = self.messages.create
+
+                def _create(*a, **kw):  # type: ignore[no-untyped-def]
+                    if "system" in kw and isinstance(kw["system"], str):
+                        kw["system"] = prefix + kw["system"]
+                    elif "system" not in kw:
+                        kw["system"] = prefix.strip()
+                    return orig(*a, **kw)
+
+                self.messages.create = _create  # type: ignore[method-assign]
+
+        anthropic.Anthropic = PatchedAnthropic
+    except (AttributeError, TypeError):
+        pass
+
+
+def _inject_system_prefix(kwargs: dict, prefix: str) -> dict:
+    """Inject the fix prefix into the messages list as/before the system message."""
+    messages = kwargs.get("messages", [])
+    if not messages:
+        return kwargs
+
+    new_messages = list(messages)
+    # Check if first message is a system message
+    if new_messages and new_messages[0].get("role") == "system":
+        existing = new_messages[0].get("content", "")
+        new_messages[0] = {**new_messages[0], "content": prefix + existing}
+    else:
+        # Prepend a new system message
+        new_messages.insert(0, {"role": "system", "content": prefix.strip()})
+
+    return {**kwargs, "messages": new_messages}
+
+
+# --- Internal -----------------------------------------------------------------
+
+def _flush_openlit() -> None:
+    """Best-effort flush of the OpenTelemetry SDK's span processors."""
+    try:
+        from opentelemetry import trace  # type: ignore[import-untyped]
+        provider = trace.get_tracer_provider()
+        # TracerProvider has force_flush(); ProxyTracerProvider does not.
+        flush_fn = getattr(provider, "force_flush", None)
+        if callable(flush_fn):
+            flush_fn(timeout_millis=4_000)
+    except Exception as exc:  # noqa: BLE001
+        print(f"[maev] OpenTelemetry flush warning: {exc}", file=sys.stderr)
+
+
+def _send_session_end(timeout: float = 5.0) -> None:
+    """HTTP POST session.end to the Maev ingest endpoint."""
+    if not _api_key or not _endpoint or not _session_id:
+        return
+
+    payload = json.dumps({
+        "session_id": _session_id,
+        "step": 0,
+        "type": "session.end",
+        "payload": {},
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    }).encode("utf-8")
+
+    req = urllib.request.Request(
+        _endpoint + "/api/ingest",
+        data=payload,
+        headers={
+            "Content-Type": "application/json",
+            "x-api-key": _api_key,
+        },
+        method="POST",
+    )
+    try:
+        urllib.request.urlopen(req, timeout=timeout)
+    except Exception as exc:  # noqa: BLE001
+        print(f"[maev] session.end flush failed: {exc}", file=sys.stderr)
+
+
+def _start(api_key: str, agent_name: str, endpoint: str, session_id: str) -> None:
+    """Internal: configure and start OpenLIT with Maev as the OTLP backend."""
+    try:
+        import openlit  # type: ignore[import-untyped]
+    except ImportError as exc:
+        raise ImportError(
+            "maev-sdk requires 'openlit'. Install it with: pip install maev-sdk"
+        ) from exc
+
+    otlp_endpoint = endpoint + "/api/ingest/otlp"
+
+    openlit.init(
+        otlp_endpoint=otlp_endpoint,
+        otlp_headers=f"x-api-key={api_key}",
+        environment="production",
+        # application_name -> gen_ai.system in OTLP spans -> agent name in dashboard
+        application_name=agent_name,
+        # session_id groups all spans from this process into one session
+        session_id=session_id,
+        collect_gpu_stats=False,
+    )
+
+
+def _shutdown() -> None:
+    """atexit handler - delegates to flush() so session.end fires exactly once."""
+    flush()

maev_sdk-0.3.0/src/maev/_instrumentors/__init__.py

@@ -0,0 +1,5 @@
+"""Instrumentation is handled by OpenLIT internally.
+
+This module is kept for future Maev-specific instrumentors
+(e.g. custom agent frameworks not supported by OpenLIT).
+"""