aops 0.1.0__py3-none-any.whl

aops/__init__.py

@@ -0,0 +1,32 @@
+"""aops — LangChain integration for AgentOps.
+
+Quick start::
+
+    import aops
+    aops.init(api_key="aops_aHR0cDovL2xvY2FsaG9zdDo4MDAw_...")
+
+    from aops.langchain import pull, chain_prompt
+"""
+
+from aops._client import AopsClient
+from aops._config import init
+from aops._exceptions import (
+    AgentNotFoundError,
+    AopsConnectionError,
+    AopsError,
+    ChainNotFoundError,
+    VersionNotFoundError,
+)
+from aops._keys import generate_key, parse_key
+
+__all__ = [
+    "init",
+    "AopsClient",
+    "generate_key",
+    "parse_key",
+    "AopsError",
+    "AgentNotFoundError",
+    "ChainNotFoundError",
+    "VersionNotFoundError",
+    "AopsConnectionError",
+]

aops/_cache.py

@@ -0,0 +1,33 @@
+import time
+from typing import Any
+
+
+class TTLCache:
+    """Simple in-memory cache with TTL expiration."""
+
+    def __init__(self, ttl: int = 300) -> None:
+        self._ttl = ttl
+        self._store: dict[str, tuple[Any, float]] = {}
+
+    def get(self, key: str) -> Any | None:
+        if self._ttl == 0:
+            return None
+        entry = self._store.get(key)
+        if entry is None:
+            return None
+        value, ts = entry
+        if time.monotonic() - ts > self._ttl:
+            del self._store[key]
+            return None
+        return value
+
+    def set(self, key: str, value: Any) -> None:
+        if self._ttl == 0:
+            return
+        self._store[key] = (value, time.monotonic())
+
+    def invalidate(self, key: str) -> None:
+        self._store.pop(key, None)
+
+    def clear(self) -> None:
+        self._store.clear()

aops/_client.py

@@ -0,0 +1,147 @@
+import uuid
+
+import httpx
+
+from aops._cache import TTLCache
+from aops._config import get_config
+from aops._exceptions import (
+    AgentNotFoundError,
+    AopsConnectionError,
+    ChainNotFoundError,
+    VersionNotFoundError,
+)
+from aops._keys import InvalidApiKeyError, parse_key
+from aops._models import AgentModel, ChainModel, ChainVersionModel
+
+
+class AopsClient:
+    """HTTP client for the AgentOps backend API."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        api_prefix: str | None = None,
+        cache_ttl: int | None = None,
+    ) -> None:
+        if api_key is not None or base_url is not None:
+            # Explicit construction — resolve host from key, then allow override
+            resolved_url = base_url or _host_from_key(api_key)
+            self._api_base = f"{resolved_url.rstrip('/')}{api_prefix or '/api/v1'}"
+            self._api_key = api_key
+            ttl = cache_ttl if cache_ttl is not None else 300
+        else:
+            config = get_config()
+            self._api_base = config.api_base
+            self._api_key = config.api_key
+            ttl = cache_ttl if cache_ttl is not None else config.cache_ttl
+
+        self._cache = TTLCache(ttl)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _headers(self) -> dict[str, str]:
+        if self._api_key:
+            return {"Authorization": f"Bearer {self._api_key}"}
+        return {}
+
+    def _get(self, path: str) -> list | dict:
+        url = f"{self._api_base}{path}"
+        try:
+            with httpx.Client() as client:
+                response = client.get(url, headers=self._headers())
+                response.raise_for_status()
+                return response.json()
+        except httpx.ConnectError as exc:
+            raise AopsConnectionError(
+                f"Cannot reach AgentOps at '{self._api_base}'. "
+                "Check that the backend is running and your API key is correct."
+            ) from exc
+        except httpx.HTTPStatusError as exc:
+            status = exc.response.status_code
+            if status == 401:
+                raise AopsConnectionError(
+                    "AgentOps rejected the API key (401 Unauthorized). "
+                    "Check that AGENTOPS_API_KEY is valid."
+                ) from exc
+            if status == 403:
+                raise AopsConnectionError(
+                    "Access denied (403 Forbidden). "
+                    "This API key may not have access to the requested agent."
+                ) from exc
+            raise AopsConnectionError(
+                f"AgentOps returned {status} for {url}"
+            ) from exc
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def get_agent_by_name(self, agent_name: str) -> AgentModel:
+        cache_key = f"agent:{agent_name}"
+        cached = self._cache.get(cache_key)
+        if cached is not None:
+            return cached
+
+        agents = [AgentModel(**a) for a in self._get("/agents/")]
+        for agent in agents:
+            if agent.name == agent_name:
+                self._cache.set(cache_key, agent)
+                return agent
+
+        raise AgentNotFoundError(
+            f"Agent '{agent_name}' not found. "
+            f"Available agents: {[a.name for a in agents] or '(none)'}"
+        )
+
+    def get_chain_by_name(self, agent_id: uuid.UUID, chain_name: str) -> ChainModel:
+        cache_key = f"chain:{agent_id}:{chain_name}"
+        cached = self._cache.get(cache_key)
+        if cached is not None:
+            return cached
+
+        chains = [ChainModel(**c) for c in self._get(f"/agents/{agent_id}/chains/")]
+        for chain in chains:
+            if chain.name == chain_name:
+                self._cache.set(cache_key, chain)
+                return chain
+
+        raise ChainNotFoundError(
+            f"Chain '{chain_name}' not found. "
+            f"Available chains: {[c.name for c in chains] or '(none)'}"
+        )
+
+    def get_chain_version(
+        self, agent_id: uuid.UUID, chain_id: uuid.UUID, version_number: int
+    ) -> ChainVersionModel:
+        cache_key = f"version:{chain_id}:{version_number}"
+        cached = self._cache.get(cache_key)
+        if cached is not None:
+            return cached
+
+        versions = [
+            ChainVersionModel(**v)
+            for v in self._get(f"/agents/{agent_id}/chains/{chain_id}/versions/")
+        ]
+        for version in versions:
+            if version.version_number == version_number:
+                self._cache.set(cache_key, version)
+                return version
+
+        available = sorted(v.version_number for v in versions)
+        raise VersionNotFoundError(
+            f"Version {version_number} not found. Available versions: {available or '(none)'}"
+        )
+
+
+def _host_from_key(api_key: str | None) -> str:
+    if api_key is None:
+        return "http://localhost:8000"
+    try:
+        host, _ = parse_key(api_key)
+        return host
+    except InvalidApiKeyError:
+        return "http://localhost:8000"

aops/_config.py

@@ -0,0 +1,90 @@
+import os
+from dataclasses import dataclass
+
+from aops._keys import InvalidApiKeyError, parse_key
+
+
+@dataclass
+class Config:
+    base_url: str = "http://localhost:8000"
+    api_prefix: str = "/api/v1"
+    api_key: str | None = None
+    cache_ttl: int = 300  # seconds; 0 = no cache
+
+    @property
+    def api_base(self) -> str:
+        return f"{self.base_url.rstrip('/')}{self.api_prefix}"
+
+
+_config: Config | None = None
+
+
+def init(
+    api_key: str | None = None,
+    *,
+    base_url: str | None = None,
+    api_prefix: str | None = None,
+    cache_ttl: int | None = None,
+) -> None:
+    """Configure the AgentOps connection.
+
+    Preferred usage — key only (host is parsed from the key automatically)::
+
+        aops.init(api_key="aops_aHR0cDovL2xvY2FsaG9zdDo4MDAw_...")
+
+    Manual URL override (e.g. for testing or reverse-proxy setups)::
+
+        aops.init(api_key="aops_...", base_url="http://my-proxy:9000")
+
+    Environment variables (when ``init()`` is not called explicitly):
+        AGENTOPS_API_KEY    — the API key (host is parsed from it)
+        AGENTOPS_BASE_URL   — overrides the host embedded in the key
+        AGENTOPS_API_PREFIX — default: /api/v1
+        AGENTOPS_CACHE_TTL  — default: 300 (seconds)
+    """
+    global _config
+
+    resolved_key = api_key or os.getenv("AGENTOPS_API_KEY")
+    explicit_url = base_url or os.getenv("AGENTOPS_BASE_URL")
+
+    resolved_url = _resolve_base_url(resolved_key, explicit_url)
+
+    _config = Config(
+        base_url=resolved_url,
+        api_prefix=api_prefix or os.getenv("AGENTOPS_API_PREFIX", "/api/v1"),
+        api_key=resolved_key,
+        cache_ttl=cache_ttl if cache_ttl is not None else int(os.getenv("AGENTOPS_CACHE_TTL", "300")),
+    )
+
+
+def get_config() -> Config:
+    global _config
+    if _config is None:
+        resolved_key = os.getenv("AGENTOPS_API_KEY")
+        explicit_url = os.getenv("AGENTOPS_BASE_URL")
+        _config = Config(
+            base_url=_resolve_base_url(resolved_key, explicit_url),
+            api_prefix=os.getenv("AGENTOPS_API_PREFIX", "/api/v1"),
+            api_key=resolved_key,
+            cache_ttl=int(os.getenv("AGENTOPS_CACHE_TTL", "300")),
+        )
+    return _config
+
+
+# ------------------------------------------------------------------
+# Internal helpers
+# ------------------------------------------------------------------
+
+def _resolve_base_url(api_key: str | None, explicit_url: str | None) -> str:
+    """Determine the base URL from the key and/or an explicit override."""
+    if explicit_url:
+        return explicit_url
+
+    if api_key:
+        try:
+            host, _ = parse_key(api_key)
+            return host
+        except InvalidApiKeyError:
+            pass  # fall through to default
+
+    return "http://localhost:8000"

aops/_exceptions.py

@@ -0,0 +1,18 @@
+class AopsError(Exception):
+    """Base exception for aops."""
+
+
+class AgentNotFoundError(AopsError):
+    """Agent with the given name does not exist."""
+
+
+class ChainNotFoundError(AopsError):
+    """Chain with the given name does not exist."""
+
+
+class VersionNotFoundError(AopsError):
+    """The requested chain version does not exist."""
+
+
+class AopsConnectionError(AopsError):
+    """Failed to connect to the AgentOps backend."""

aops/_keys.py

@@ -0,0 +1,83 @@
+"""API key utilities for aops.
+
+Key format:
+    aops_{base64url(host)}_{secret_token}
+
+Example:
+    host  = "http://localhost:8000"
+    key   = "aops_aHR0cDovL2xvY2FsaG9zdDo4MDAw_xK9mP2abcXYZ..."
+
+The host is base64url-encoded (no padding) inside the key, so the library
+can resolve the AgentOps server without a separate base_url setting.
+"""
+
+import base64
+import secrets
+
+_PREFIX = "aops"
+_SEP = "_"
+
+
+class InvalidApiKeyError(ValueError):
+    """Raised when an API key cannot be parsed."""
+
+
+def generate_key(host: str) -> str:
+    """Generate a new API key that embeds *host*.
+
+    This helper is intended for the AgentOps backend when issuing keys.
+    The returned key must be stored (hashed) and should be shown to the
+    user only once.
+
+    Args:
+        host: Full base URL of the AgentOps server,
+              e.g. ``"http://localhost:8000"``.
+
+    Returns:
+        A key string of the form ``"aops_{encoded_host}_{token}"``.
+    """
+    encoded_host = _encode_host(host)
+    token = secrets.token_urlsafe(32)
+    return f"{_PREFIX}{_SEP}{encoded_host}{_SEP}{token}"
+
+
+def parse_key(api_key: str) -> tuple[str, str]:
+    """Parse an API key and return ``(host, token)``.
+
+    Args:
+        api_key: A key produced by :func:`generate_key`.
+
+    Returns:
+        ``(host, token)`` tuple where *host* is the raw base URL string.
+
+    Raises:
+        :class:`InvalidApiKeyError` if the key format is invalid.
+    """
+    parts = api_key.split(_SEP, 2)
+    if len(parts) != 3 or parts[0] != _PREFIX:
+        raise InvalidApiKeyError(
+            f"Invalid API key format. Expected 'aops_<host>_<token>', got: '{api_key[:12]}...'"
+        )
+    _, encoded_host, token = parts
+    try:
+        host = _decode_host(encoded_host)
+    except Exception as exc:
+        raise InvalidApiKeyError(
+            f"Cannot decode host from API key: {exc}"
+        ) from exc
+    return host, token
+
+
+# ------------------------------------------------------------------
+# Internal helpers
+# ------------------------------------------------------------------
+
+def _encode_host(host: str) -> str:
+    """base64url-encode *host* without padding."""
+    return base64.urlsafe_b64encode(host.encode()).decode().rstrip("=")
+
+
+def _decode_host(encoded: str) -> str:
+    """Decode a base64url *encoded* host (handles missing padding)."""
+    padded = encoded + "=" * (-len(encoded) % 4)
+    return base64.urlsafe_b64decode(padded).decode()

aops/_models.py

@@ -0,0 +1,33 @@
+import uuid
+from datetime import datetime
+
+from pydantic import BaseModel
+
+
+class AgentModel(BaseModel):
+    id: uuid.UUID
+    name: str
+    description: str | None
+    created_at: datetime
+    updated_at: datetime
+
+
+class ChainModel(BaseModel):
+    id: uuid.UUID
+    agent_id: uuid.UUID
+    name: str
+    description: str | None
+    persona: str
+    content: str
+    created_at: datetime
+    updated_at: datetime
+
+
+class ChainVersionModel(BaseModel):
+    id: uuid.UUID
+    chain_id: uuid.UUID
+    persona: str
+    content: str
+    message: str
+    version_number: int
+    created_at: datetime

aops/langchain/__init__.py

@@ -0,0 +1,3 @@
+from aops.langchain._loader import chain_prompt, pull
+
+__all__ = ["pull", "chain_prompt"]

aops/langchain/_loader.py

@@ -0,0 +1,166 @@
+import functools
+import inspect
+from typing import Callable
+
+from langchain_core.prompts import SystemMessagePromptTemplate
+
+from aops._client import AopsClient
+
+
+def _to_system_prompt(persona: str, content: str) -> SystemMessagePromptTemplate:
+    """Convert AgentOps chain fields into a SystemMessagePromptTemplate.
+
+    Both ``persona`` and ``content`` are agent-authored system-level instructions,
+    merged into a single SystemMessage:
+
+        # Persona
+        <persona text>
+
+        # Content
+        <content text — may contain {template_variables}>
+
+    ``persona`` is treated as a fixed string (its braces are escaped).
+    ``content`` may contain LangChain template variables in single braces,
+    e.g. ``"Answer in {language}"``.
+    To include a literal brace in content use double braces: ``{{`` or ``}}``.
+    """
+    persona_escaped = persona.replace("{", "{{").replace("}", "}}")
+    system_text = f"# Persona\n{persona_escaped}\n\n# Content\n{content}"
+    return SystemMessagePromptTemplate.from_template(system_text)
+
+
+def pull(
+    ref: str,
+    *,
+    version: int | None = None,
+    client: AopsClient | None = None,
+) -> SystemMessagePromptTemplate:
+    """Fetch a chain from AgentOps and return it as a SystemMessagePromptTemplate.
+
+    Args:
+        ref:     ``"agent-name/chain-name"`` reference string.
+        version: Specific version number to load.  ``None`` loads the current
+                 (latest saved) chain content.
+        client:  Optional pre-configured :class:`~aops._client.AopsClient`.
+                 When omitted the global configuration is used.
+
+    Returns:
+        A :class:`langchain_core.prompts.SystemMessagePromptTemplate` combining
+        the chain's ``persona`` and ``content`` into a single system message.
+
+    Example::
+
+        from aops.langchain import pull
+
+        prompt = pull("customer-support/greeter")
+        prompt_v2 = pull("customer-support/greeter", version=2)
+
+        chain = prompt | ChatOpenAI() | StrOutputParser()
+        chain.invoke({"topic": "billing"})
+    """
+    if "/" not in ref:
+        raise ValueError(
+            f"Invalid ref '{ref}'. Expected format: 'agent-name/chain-name'."
+        )
+
+    agent_name, chain_name = ref.split("/", 1)
+    c = client or AopsClient()
+
+    agent = c.get_agent_by_name(agent_name)
+    chain = c.get_chain_by_name(agent.id, chain_name)
+
+    if version is not None:
+        v = c.get_chain_version(agent.id, chain.id, version)
+        return _to_system_prompt(v.persona, v.content)
+
+    return _to_system_prompt(chain.persona, chain.content)
+
+
+def chain_prompt(
+    agent_name: str,
+    chain_name: str,
+    *,
+    version: int | None = None,
+    client: AopsClient | None = None,
+):
+    """Decorator that injects a ``SystemMessagePromptTemplate`` from AgentOps.
+
+    The prompt is fetched once on the first call and then served from the
+    client-level cache on subsequent calls.
+
+    **Function decorator** — the resolved prompt is passed as the first
+    positional argument::
+
+        @chain_prompt("my-agent", "summariser")
+        def summarise(prompt: SystemMessagePromptTemplate, text: str) -> str:
+            return (prompt | ChatOpenAI()).invoke({"text": text})
+
+        result = summarise(text="Long article...")
+
+    **Class decorator** — the resolved prompt is passed as the second
+    positional argument to ``__init__`` (after ``self``)::
+
+        @chain_prompt("my-agent", "summariser")
+        class Summariser:
+            def __init__(self, prompt: SystemMessagePromptTemplate) -> None:
+                self.chain = prompt | ChatOpenAI()
+
+            def run(self, text: str) -> str:
+                return self.chain.invoke({"text": text})
+
+        summariser = Summariser()
+        result = summariser.run(text="Long article...")
+
+    Args:
+        agent_name: Name of the agent registered in AgentOps.
+        chain_name: Name of the chain within that agent.
+        version:    Version number to pin.  ``None`` = latest.
+        client:     Optional custom :class:`~aops._client.AopsClient`.
+    """
+
+    def decorator(target: type | Callable) -> type | Callable:
+        if inspect.isclass(target):
+            return _wrap_class(target, agent_name, chain_name, version, client)
+        return _wrap_function(target, agent_name, chain_name, version, client)
+
+    return decorator
+
+
+# ------------------------------------------------------------------
+# Internal wrappers
+# ------------------------------------------------------------------
+
+def _wrap_function(
+    func: Callable,
+    agent_name: str,
+    chain_name: str,
+    version: int | None,
+    client: AopsClient | None,
+) -> Callable:
+    ref = f"{agent_name}/{chain_name}"
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        prompt = pull(ref, version=version, client=client)
+        return func(prompt, *args, **kwargs)
+
+    return wrapper
+
+
+def _wrap_class(
+    cls: type,
+    agent_name: str,
+    chain_name: str,
+    version: int | None,
+    client: AopsClient | None,
+) -> type:
+    ref = f"{agent_name}/{chain_name}"
+    original_init = cls.__init__
+
+    @functools.wraps(original_init)
+    def new_init(self, *args, **kwargs):
+        prompt = pull(ref, version=version, client=client)
+        original_init(self, prompt, *args, **kwargs)
+
+    cls.__init__ = new_init
+    return cls

aops-0.1.0.dist-info/METADATA

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: aops
+Version: 0.1.0
+Summary: LangChain integration library for AOps
+Requires-Python: >=3.12
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: langchain-core>=0.3
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Dynamic: license-file

aops-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+aops/__init__.py,sha256=0DoHwiVNCV_nQPwSjWfElKpg0YniWe9OgOvI92lYtVI,665
+aops/_cache.py,sha256=p28W9OGK94dJdzPRUfdxHGxLpESIOFjJValitIMPmLI,854
+aops/_client.py,sha256=fvJTgT6oid9ZlBKUOsWr10GzEnKC-shHyu0kLyYpwBk,5262
+aops/_config.py,sha256=oS7e_I4TevUsLRWaVEe8p5byXxjUFIjHFggBTMw3pbQ,2764
+aops/_exceptions.py,sha256=M51X8XcSLJUGAl6j0ftT4-Kw68rtXCH1Ar8vKEeCiwk,433
+aops/_keys.py,sha256=hpHy9l8Rr4mVDXfYOFR4KSk1QYdyB9m0iR4ZQEiOJUY,2427
+aops/_models.py,sha256=09JWGzuAi-SPN3lEsNbR8oKX3oFb2GIvqTcLKGRK1yY,594
+aops/langchain/__init__.py,sha256=4eHY60BBd8rvy3LEHlBtw4yrMOiHww67-QRDrl3hkZU,90
+aops/langchain/_loader.py,sha256=bXlX1ll67mgcBbSICJgPKSkHXAHjuv1pzhX21NigQDA,5330
+aops-0.1.0.dist-info/licenses/LICENSE,sha256=HxkQT8PjlbSHf5It346-bFDw4UAUPSXgvDBQ_csOXDU,1067
+aops-0.1.0.dist-info/METADATA,sha256=KhegFZmRAvgTBaM2SVwUbDn_UDNybl9m879WxwJGREM,447
+aops-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+aops-0.1.0.dist-info/top_level.txt,sha256=EaJFL4yXv8nlbsIcOE1I_HshvjLc6fWDIPqJZ-HESfs,5
+aops-0.1.0.dist-info/RECORD,,

aops-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

aops-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Park Kibum
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aops-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+aops