runvault 0.1.1__py3-none-any.whl

runvault/__init__.py

@@ -0,0 +1,71 @@
+"""RunVault SDK.
+
+Core imports are eager. LLM factory functions are loaded lazily on first
+access so importing sdk never pulls in langchain, openai, anthropic, etc.
+unless the caller actually uses them.
+
+Usage:
+
+    from runvault import RunVault, ChatOpenAI, get_rv
+"""
+
+from __future__ import annotations
+
+import importlib
+
+from runvault.client import RunVault
+from runvault.context import get_rv
+from runvault.exceptions import (
+    AuthenticationError,
+    BudgetExceededError,
+    ConfigurationError,
+    ConnectionError,
+    LLMProviderError,
+    ProxyError,
+    RegistrationError,
+    RunVaultError,
+    TokenExpiredError,
+)
+
+__all__ = [
+    # Entry point
+    "RunVault",
+    # Context
+    "get_rv",
+    # Exceptions
+    "RunVaultError",
+    "AuthenticationError",
+    "BudgetExceededError",
+    "ConfigurationError",
+    "ConnectionError",
+    "LLMProviderError",
+    "ProxyError",
+    "RegistrationError",
+    "TokenExpiredError",
+    # LLM factories (lazy)
+    "ChatOpenAI",
+    "OpenAI",
+    "AsyncOpenAI",
+    "ChatAnthropic",
+    "Anthropic",
+    "AsyncAnthropic",
+    "ChatGoogleGenerativeAI",
+]
+
+# Maps factory name → module path. Loaded on first attribute access.
+_LAZY: dict[str, str] = {
+    "ChatOpenAI":              "runvault.llm.openai",
+    "OpenAI":                  "runvault.llm.openai",
+    "AsyncOpenAI":             "runvault.llm.openai",
+    "ChatAnthropic":           "runvault.llm.anthropic",
+    "Anthropic":               "runvault.llm.anthropic",
+    "AsyncAnthropic":          "runvault.llm.anthropic",
+    "ChatGoogleGenerativeAI":  "runvault.llm.google",
+}
+
+
+def __getattr__(name: str):
+    if name in _LAZY:
+        module = importlib.import_module(_LAZY[name])
+        return getattr(module, name)
+    raise AttributeError(f"module 'sdk' has no attribute {name!r}")

runvault/adapters/__init__.py

@@ -0,0 +1,16 @@
+"""Framework adapter registry.
+
+Maps framework name strings (used in runvault.init(framework=...)) to their
+wrap_* functions. Each wrap function accepts (agent, app) and calls
+agent._bind_adapter() to attach the wrapper.
+
+To add a new adapter:
+  1. Create adapters/<framework>.py following langgraph.py as the reference.
+  2. Add an entry here.
+"""
+
+from runvault.adapters.langgraph import wrap_langgraph
+
+ADAPTERS: dict[str, callable] = {
+    "langgraph": wrap_langgraph,
+}

runvault/adapters/langgraph.py

@@ -0,0 +1,126 @@
+"""RunVault LangGraph adapter.
+
+Wraps a compiled LangGraph graph so that the RunVault Agent is set on the
+ContextVar for the duration of each invocation. Nodes inside the graph
+can then call get_rv() without any explicit state or parameter threading.
+
+Usage:
+
+    from runvault import RunVault, ChatOpenAI
+
+    runvault = RunVault(api_key="rv_live_...", be_url="https://your-runvault-backend")
+    llm = ChatOpenAI(model="gpt-4o-mini")
+
+    agent = runvault.init(
+        framework="langgraph",
+        app=compiled_graph,
+        agent_id="research-v1",
+        name="Research Agent",
+    )
+
+    result = agent.invoke({"input": "..."})
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from runvault.context import _current_agent
+from runvault.exceptions import RunVaultError
+
+if TYPE_CHECKING:
+    from runvault.runtime.agent import Agent
+
+
+def _unwrap_rv_error(exc: BaseException) -> RunVaultError | None:
+    """Walk the exception cause chain and return the first RunVaultError found.
+
+    LLM SDKs (e.g. OpenAI) wrap exceptions raised inside httpx.send into
+    their own types (APIConnectionError). This recovers the original
+    RunVaultError so callers see a meaningful exception instead of a generic
+    connection error.
+    """
+    current: BaseException | None = exc
+    for _ in range(10):
+        if isinstance(current, RunVaultError):
+            return current
+        cause = getattr(current, "__cause__", None) or getattr(current, "__context__", None)
+        if cause is None or cause is current:
+            break
+        current = cause
+    return None
+
+
+class _LangGraphWrapper:
+    """Sets the RunVault Agent on the ContextVar for each graph invocation."""
+
+    def __init__(self, agent: Agent, graph: Any) -> None:
+        self._agent = agent
+        self._graph = graph
+
+    def invoke(self, *args: Any, **kwargs: Any) -> Any:
+        """Invoke the graph synchronously with RunVault context active."""
+        token = _current_agent.set(self._agent)
+        try:
+            return self._graph.invoke(*args, **kwargs)
+        except Exception as exc:
+            rv_error = _unwrap_rv_error(exc)
+            if rv_error is not None:
+                raise rv_error
+            raise
+        finally:
+            _current_agent.reset(token)
+
+    def stream(self, *args: Any, **kwargs: Any):
+        """Stream the graph synchronously with RunVault context active."""
+        token = _current_agent.set(self._agent)
+        try:
+            yield from self._graph.stream(*args, **kwargs)
+        except Exception as exc:
+            rv_error = _unwrap_rv_error(exc)
+            if rv_error is not None:
+                raise rv_error
+            raise
+        finally:
+            _current_agent.reset(token)
+
+    async def ainvoke(self, *args: Any, **kwargs: Any) -> Any:
+        """Invoke the graph asynchronously with RunVault context active."""
+        token = _current_agent.set(self._agent)
+        try:
+            return await self._graph.ainvoke(*args, **kwargs)
+        except Exception as exc:
+            rv_error = _unwrap_rv_error(exc)
+            if rv_error is not None:
+                raise rv_error
+            raise
+        finally:
+            _current_agent.reset(token)
+
+    async def astream(self, *args: Any, **kwargs: Any):
+        """Stream the graph asynchronously with RunVault context active."""
+        token = _current_agent.set(self._agent)
+        try:
+            async for chunk in self._graph.astream(*args, **kwargs):
+                yield chunk
+        except Exception as exc:
+            rv_error = _unwrap_rv_error(exc)
+            if rv_error is not None:
+                raise rv_error
+            raise
+        finally:
+            _current_agent.reset(token)
+
+
+def wrap_langgraph(agent: Agent, app: Any) -> None:
+    """Wrap a compiled LangGraph graph and bind it to the Agent.
+
+    Creates a _LangGraphWrapper and attaches it via agent._bind_adapter()
+    so agent.invoke() / agent.stream() / etc. delegate to the wrapper.
+
+    Args:
+        agent: The Agent returned by RunVault.init().
+        app:   A compiled LangGraph graph (result of StateGraph.compile()).
+    """
+    wrapper = _LangGraphWrapper(agent=agent, graph=app)
+    agent._bind_adapter(wrapper)

runvault/auth/registration.py

@@ -0,0 +1,63 @@
+"""Agent registration — POST /auth/agents/runs."""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from dataclasses import dataclass
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class AgentInfo:
+    id: uuid.UUID
+    agent_id: str
+    name: str
+    project_id: uuid.UUID
+    run_id: uuid.UUID
+    budget: float | None
+    budget_alert_threshold: float | None
+    llm_provider: str
+    proxy_url: str    # base proxy URL returned by the backend on registration
+    created: bool
+
+
+def register(
+    http,
+    api_key: str,
+    agent_id: str,
+    name: str,
+    budget: float | None = None,
+    budget_alert_threshold: float | None = None,
+) -> tuple[AgentInfo, str]:
+    """Call POST /auth/agents/runs and return (AgentInfo, jwt_token)."""
+    payload: dict = {"agent_id": agent_id, "name": name, "rv_api_key": api_key}
+    if budget is not None:
+        payload["budget"] = budget
+    if budget_alert_threshold is not None:
+        payload["budget_alert_threshold"] = budget_alert_threshold
+
+    data = http.post("/auth/agents/runs", payload)
+
+    token: str = data["token"]
+    info = AgentInfo(
+        id=uuid.UUID(data["agent_id"]),
+        agent_id=agent_id,
+        name=name,
+        project_id=uuid.UUID("00000000-0000-0000-0000-000000000000"),
+        run_id=uuid.UUID(data["run_id"]),
+        budget=budget,
+        budget_alert_threshold=budget_alert_threshold,
+        llm_provider=data["llm_provider"],
+        proxy_url=data["proxy_url"],
+        created=data["agent_created"],
+    )
+
+    log.info(
+        "RunVault agent %s: agent_id=%s id=%s run_id=%s provider=%s proxy=%s",
+        "registered" if info.created else "found existing",
+        agent_id, info.id, info.run_id, info.llm_provider, info.proxy_url,
+    )
+
+    return info, token

runvault/client.py

@@ -0,0 +1,112 @@
+"""RunVault SDK entry point.
+
+Usage:
+
+    from runvault import RunVault, ChatOpenAI
+
+    rv = RunVault(
+        api_key="rv_live_...",
+        be_url="https://your-runvault-backend",
+    )
+    llm = ChatOpenAI(model="gpt-4o-mini")
+    graph = build_graph(llm)
+
+    agent = rv.init(framework="langgraph", app=graph,
+                    agent_id="research-v1", name="Research Agent")
+    result = agent.invoke({"input": "..."})
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from runvault.adapters import ADAPTERS
+from runvault.auth.registration import register
+from runvault.http.backend import BackendClient
+from runvault.runtime.agent import Agent
+
+log = logging.getLogger(__name__)
+
+
+class RunVault:
+    """RunVault SDK client.
+
+    Args:
+        api_key: Active RunVault project API key (rv_live_…). Always required.
+        be_url:  Base URL of the RunVault backend. Always required.
+        timeout: HTTP request timeout in seconds for backend calls.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        be_url: str,
+        timeout: int = 10,
+    ) -> None:
+        self._api_key = api_key
+        self._http = BackendClient(be_url=be_url, timeout=timeout)
+
+    def _register_agent(
+        self,
+        agent_id: str,
+        name: str,
+        budget: float | None = None,
+        budget_alert_threshold: float | None = None,
+    ) -> Agent:
+        """Register an agent and obtain a proxy JWT (internal).
+
+        Idempotent — the backend returns the existing agent record but always
+        issues a fresh run_id and JWT, scoping each execution for spend tracking.
+        Called by init(). Not part of the public API in v1.
+        """
+        info, token = register(
+            http=self._http,
+            api_key=self._api_key,
+            agent_id=agent_id,
+            name=name,
+            budget=budget,
+            budget_alert_threshold=budget_alert_threshold,
+        )
+        return Agent(info=info, token=token, http=self._http)
+
+    def init(
+        self,
+        framework: str,
+        app: Any,
+        agent_id: str,
+        name: str,
+        budget: float | None = None,
+        budget_alert_threshold: float | None = None,
+    ) -> Agent:
+        """Register an agent and wrap a framework graph in one call.
+
+        Args:
+            framework: Framework name (e.g. "langgraph").
+            app:       Compiled graph or runnable to wrap.
+            agent_id:  Stable identifier for this agent.
+            name:      Human-readable name.
+            budget:    Optional spending cap in USD.
+            budget_alert_threshold: Optional alert percentage (0–100).
+
+        Returns:
+            Agent ready to invoke.
+
+        Raises:
+            ValueError: If the framework is not supported.
+        """
+        try:
+            wrap = ADAPTERS[framework]
+        except KeyError:
+            raise ValueError(
+                f"Unknown framework {framework!r}. "
+                f"Supported: {sorted(ADAPTERS)}"
+            )
+        agent = self._register_agent(
+            agent_id=agent_id,
+            name=name,
+            budget=budget,
+            budget_alert_threshold=budget_alert_threshold,
+        )
+        wrap(agent, app)
+        return agent

runvault/context.py

@@ -0,0 +1,43 @@
+"""RunVault context variable.
+
+Provides ambient access to the active Agent from inside framework nodes
+without passing it through graph state.
+
+Usage inside a node:
+
+    from runvault import get_rv
+
+    def my_node(state):
+        agent = get_rv()
+        # agent.info.id, agent.token, agent.budget_remaining(), etc.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from runvault.runtime.agent import Agent
+
+_current_agent: ContextVar[Agent] = ContextVar("_current_agent")
+
+
+def get_rv() -> Agent:
+    """Return the active Agent for the current execution context.
+
+    Set automatically by the framework adapter wrapper around each
+    graph invocation. Isolated per async task and per thread — concurrent
+    invocations on the same process never see each other's Agent.
+
+    Raises:
+        RuntimeError: If called outside a graph wrapped via runvault.init().
+    """
+    try:
+        return _current_agent.get()
+    except LookupError:
+        raise RuntimeError(
+            "No active RunVault agent. "
+            "Wrap your graph with runvault.init(framework=..., app=...) "
+            "before invoking it."
+        )

runvault/exceptions/__init__.py

@@ -0,0 +1,16 @@
+from .auth import AuthenticationError, ConfigurationError, ConnectionError, RegistrationError
+from .base import RunVaultError
+from .provider import LLMProviderError
+from .proxy import BudgetExceededError, ProxyError, TokenExpiredError
+
+__all__ = [
+    "RunVaultError",
+    "AuthenticationError",
+    "BudgetExceededError",
+    "ConfigurationError",
+    "ConnectionError",
+    "LLMProviderError",
+    "ProxyError",
+    "RegistrationError",
+    "TokenExpiredError",
+]

runvault/exceptions/auth.py

@@ -0,0 +1,17 @@
+from .base import RunVaultError
+
+
+class AuthenticationError(RunVaultError):
+    """API key is invalid, revoked, or has no linked LLM vault key."""
+
+
+class RegistrationError(RunVaultError):
+    """Agent registration with the RunVault backend failed."""
+
+
+class ConnectionError(RunVaultError):
+    """RunVault backend could not be reached (network error or timeout)."""
+
+
+class ConfigurationError(RunVaultError):
+    """Required SDK configuration is missing or invalid (e.g. no proxy URL)."""

runvault/exceptions/base.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+
+class RunVaultError(Exception):
+    """Base class for all RunVault SDK exceptions.
+
+    Attributes:
+        status_code:  HTTP status code from the backend or proxy, if available.
+        error_code:   Machine-readable code (e.g. ``BUDGET_CAP_REACHED``).
+        user_string:  Human-readable message safe to display to end users.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        error_code: str | None = None,
+        user_string: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_code = error_code
+        self.user_string = user_string if user_string is not None else message

runvault/exceptions/provider.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from .base import RunVaultError
+
+
+class LLMProviderError(RunVaultError):
+    """The upstream LLM provider returned an error response.
+
+    This wraps provider HTTP errors so agents can catch all LLM failures
+    from a single exception type without importing provider-specific SDKs.
+
+    Attributes:
+        provider:  Name of the provider (e.g. ``"openai"``, ``"anthropic"``).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        provider: str | None = None,
+        **kwargs,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.provider = provider

runvault/exceptions/proxy.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from .base import RunVaultError
+
+
+class BudgetExceededError(RunVaultError):
+    """Agent's spending budget is exhausted — the proxy denied the request.
+
+    Attributes:
+        remaining_usd:  Balance remaining at time of denial (may be 0 or
+                        slightly negative due to estimation rounding).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        remaining_usd: float | None = None,
+        **kwargs,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.remaining_usd = remaining_usd
+
+
+class TokenExpiredError(RunVaultError):
+    """Proxy JWT has expired — call RunVault.init() again to get a new one."""
+
+
+class ProxyError(RunVaultError):
+    """Generic proxy-level error (e.g. version mismatch, proxy misconfiguration)."""

runvault/http/backend.py

@@ -0,0 +1,116 @@
+"""BackendClient — single httpx transport for all SDK→backend REST calls.
+
+All modules that need to talk to the RunVault backend (registration,
+budget queries, spending records, payments) use this client.  Error
+parsing and typed exception raising are centralised here so callers
+never have to touch raw HTTP.
+"""
+
+from __future__ import annotations
+
+import httpx
+
+from runvault.exceptions import AuthenticationError, ConnectionError, RegistrationError
+
+
+class BackendClient:
+    """Thin httpx wrapper for the RunVault backend.
+
+    Args:
+        be_url:  Backend base URL (e.g. http://backend:30080).
+        timeout: Request timeout in seconds applied to connect + write.
+                 Read timeout is left unlimited because some backend
+                 calls (e.g. Lithic card issuance) may be slow.
+    """
+
+    def __init__(self, be_url: str, timeout: int = 10) -> None:
+        self._be_url = be_url.rstrip("/")
+        self._client = httpx.Client(
+            timeout=httpx.Timeout(connect=float(timeout), read=None,
+                                  write=float(timeout), pool=float(timeout)),
+            headers={"User-Agent": "runvault-python/2.0"},
+        )
+
+    def post(self, path: str, body: dict) -> dict:
+        """POST to the backend and return the parsed JSON body.
+
+        Raises a typed RunVaultError on any non-200 response, connection
+        failure, or timeout.
+        """
+        try:
+            resp = self._client.post(f"{self._be_url}{path}", json=body)
+        except httpx.ConnectError as exc:
+            raise ConnectionError(
+                f"Cannot reach RunVault backend at {self._be_url}: {exc}",
+                user_string="Cannot reach the RunVault backend. Check your network connection.",
+            ) from exc
+        except httpx.TimeoutException as exc:
+            raise ConnectionError(
+                f"Request to RunVault backend timed out: {exc}",
+                user_string="Request to RunVault backend timed out. Try again in a moment.",
+            ) from exc
+        return self._handle(resp)
+
+    def get(self, path: str) -> dict:
+        """GET from the backend and return the parsed JSON body."""
+        try:
+            resp = self._client.get(f"{self._be_url}{path}")
+        except httpx.ConnectError as exc:
+            raise ConnectionError(
+                f"Cannot reach RunVault backend at {self._be_url}: {exc}",
+                user_string="Cannot reach the RunVault backend. Check your network connection.",
+            ) from exc
+        except httpx.TimeoutException as exc:
+            raise ConnectionError(
+                f"Request to RunVault backend timed out: {exc}",
+                user_string="Request to RunVault backend timed out. Try again in a moment.",
+            ) from exc
+        return self._handle(resp)
+
+    def close(self) -> None:
+        self._client.close()
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _handle(self, resp: httpx.Response) -> dict:
+        if resp.status_code == 200:
+            return resp.json()
+        msg, code, user_str = self._parse_error(resp)
+        if resp.status_code == 401:
+            raise AuthenticationError(
+                msg or "Invalid or expired API key.",
+                status_code=401,
+                error_code=code or "INVALID_API_KEY",
+                user_string=user_str or "Invalid or expired API key.",
+            )
+        if resp.status_code == 400:
+            raise AuthenticationError(
+                msg or "Bad request.",
+                status_code=400,
+                error_code=code,
+                user_string=user_str or msg or "Bad request.",
+            )
+        raise RegistrationError(
+            msg or f"Backend error (HTTP {resp.status_code}).",
+            status_code=resp.status_code,
+            error_code=code,
+            user_string=user_str or f"RunVault backend returned an unexpected error.",
+        )
+
+    @staticmethod
+    def _parse_error(resp: httpx.Response) -> tuple[str, str | None, str | None]:
+        """Extract (internal_message, error_code, user_string) from an error response."""
+        try:
+            body = resp.json()
+            detail = body.get("detail", {})
+            if isinstance(detail, dict):
+                return (
+                    detail.get("detail", resp.text),
+                    detail.get("code"),
+                    detail.get("user_string", resp.text),
+                )
+            return str(detail) or resp.text, None, str(detail) or resp.text
+        except Exception:
+            return resp.text, None, resp.text