agentgear-ai 0.1.16__py3-none-any.whl

agentgear/__init__.py

@@ -0,0 +1,18 @@
+"""
+AgentGear SDK and utilities.
+
+Primary exports:
+- AgentGearClient: backend client for logging runs/spans/prompts
+- observe: decorator for capturing LLM calls
+- trace: context manager for spans
+- Prompt: prompt templating and version metadata helper
+"""
+
+from agentgear.sdk.client import AgentGearClient
+from agentgear.sdk.decorators import observe
+from agentgear.sdk.trace import trace
+from agentgear.sdk.prompt import Prompt
+
+__version__ = "0.1.9"
+
+__all__ = ["AgentGearClient", "observe", "trace", "Prompt", "__version__"]

agentgear/cli/__init__.py

@@ -0,0 +1 @@
+# CLI package

agentgear/cli/main.py

@@ -0,0 +1,125 @@
+import subprocess
+from typing import List, Optional
+
+import typer
+
+from agentgear.server.app.auth import generate_token
+from agentgear.server.app.config import get_settings
+from agentgear.server.app.db import Base, SessionLocal, engine
+from agentgear.server.app.migrations import apply_migrations
+from agentgear.server.app.models import APIKey, Project, Prompt, PromptVersion, Run
+
+app = typer.Typer(help="AgentGear CLI")
+
+
+@app.command()
+def init_db():
+    """Initialize database tables."""
+    Base.metadata.create_all(bind=engine)
+    apply_migrations(engine)
+    typer.echo("Database initialized.")
+
+
+@app.command()
+def create_project(name: str = typer.Option(...), description: Optional[str] = typer.Option(None)):
+    """Create a new project."""
+    db = SessionLocal()
+    try:
+        project = Project(name=name, description=description)
+        db.add(project)
+        db.commit()
+        db.refresh(project)
+        typer.echo(f"Created project {project.id} ({project.name})")
+    finally:
+        db.close()
+
+
+@app.command()
+def list_projects():
+    """List projects."""
+    db = SessionLocal()
+    try:
+        projects = db.query(Project).all()
+        for p in projects:
+            typer.echo(f"{p.id}\t{p.name}\t{p.created_at}")
+    finally:
+        db.close()
+
+
+@app.command()
+def create_token(
+    project_id: str,
+    scopes: List[str] = typer.Option(["runs.write", "prompts.read", "prompts.write", "tokens.manage"]),
+):
+    """Create an API token for a project."""
+    db = SessionLocal()
+    try:
+        project = db.query(Project).filter(Project.id == project_id).first()
+        if not project:
+            typer.echo("Project not found")
+            raise typer.Exit(code=1)
+        raw, hashed = generate_token()
+        record = APIKey(project_id=project.id, key_hash=hashed, scopes=scopes)
+        db.add(record)
+        db.commit()
+        db.refresh(record)
+        typer.echo(f"Token created for project {project.name}")
+        typer.echo("Save this token now; it will not be shown again:")
+        typer.echo(raw)
+    finally:
+        db.close()
+
+
+@app.command()
+def demo_data():
+    """Seed demo data."""
+    db = SessionLocal()
+    try:
+        project = Project(name="Demo Project", description="Sample project")
+        db.add(project)
+        db.commit()
+        db.refresh(project)
+
+        prompt = Prompt(project_id=project.id, name="greeting", description="Greeting prompt")
+        db.add(prompt)
+        db.commit()
+        db.refresh(prompt)
+
+        pv = PromptVersion(prompt_id=prompt.id, version=1, content="Hello {{name}}")
+        db.add(pv)
+        db.commit()
+
+        run = Run(
+            project_id=project.id,
+            prompt_version_id=pv.id,
+            name="demo-run",
+            input_text="name=Agent",
+            output_text="Hello Agent",
+            token_input=5,
+            token_output=5,
+            cost=0.0001,
+            latency_ms=120,
+        )
+        db.add(run)
+        db.commit()
+        typer.echo("Demo data created.")
+        typer.echo(f"Project ID: {project.id}")
+    finally:
+        db.close()
+
+
+@app.command()
+def ui(host: Optional[str] = None, port: Optional[int] = None, reload: bool = True):
+    """Run FastAPI server with uvicorn."""
+    settings = get_settings()
+    host = host or settings.api_host
+    port = port or settings.api_port
+    args = ["uvicorn", "agentgear.server.app.main:app", "--host", host, "--port", str(port)]
+    if reload:
+        args.append("--reload")
+    typer.echo(f"Starting AgentGear API on {host}:{port}")
+    subprocess.run(args, check=False)
+
+
+if __name__ == "__main__":
+    app()

agentgear/sdk/__init__.py

@@ -0,0 +1,6 @@
+from agentgear.sdk.client import AgentGearClient
+from agentgear.sdk.decorators import observe
+from agentgear.sdk.trace import trace
+from agentgear.sdk.prompt import Prompt
+
+__all__ = ["AgentGearClient", "observe", "trace", "Prompt"]

agentgear/sdk/client.py

@@ -0,0 +1,276 @@
+import time
+from typing import Any, Dict, Optional
+
+import httpx
+
+from agentgear.server.app.db import SessionLocal
+from agentgear.server.app.models import Project, Prompt, PromptVersion, Run, Span
+
+
+class AgentGearClient:
+    """Client for sending observability data to AgentGear backend."""
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8000",
+        api_key: Optional[str] = None,
+        project_id: Optional[str] = None,
+        local: bool = False,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.project_id = project_id
+        self.local = local
+        if not self.local and not self.api_key:
+            raise ValueError("api_key is required in remote mode")
+        self._http = httpx.Client(base_url=self.base_url, timeout=10.0)
+
+    def _headers(self) -> Dict[str, str]:
+        headers = {}
+        if self.api_key:
+            headers["X-AgentGear-Key"] = self.api_key
+        return headers
+
+    def log_run(
+        self,
+        name: Optional[str] = None,
+        input_text: Optional[str] = None,
+        output_text: Optional[str] = None,
+        prompt_version_id: Optional[str] = None,
+        token_usage: Optional[dict[str, Any]] = None,
+        cost: Optional[float] = None,
+        latency_ms: Optional[float] = None,
+        error: Optional[str] = None,
+        metadata: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        project_id = self._require_project()
+        payload = {
+            "project_id": project_id,
+            "prompt_version_id": prompt_version_id,
+            "name": name,
+            "input_text": input_text,
+            "output_text": output_text,
+            "token_usage": token_usage,
+            "cost": cost,
+            "latency_ms": latency_ms,
+            "error": error,
+            "metadata": metadata,
+        }
+        if self.local:
+            return self._log_run_local(payload)
+        resp = self._http.post("/api/runs", json=payload, headers=self._headers())
+        resp.raise_for_status()
+        return resp.json()
+
+    def log_span(
+        self,
+        run_id: str,
+        name: str,
+        parent_id: Optional[str] = None,
+        start_time: Optional[str] = None,
+        end_time: Optional[str] = None,
+        latency_ms: Optional[float] = None,
+        metadata: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        project_id = self._require_project()
+        payload = {
+            "project_id": project_id,
+            "run_id": run_id,
+            "parent_id": parent_id,
+            "name": name,
+            "start_time": start_time,
+            "end_time": end_time,
+            "latency_ms": latency_ms,
+            "metadata": metadata,
+        }
+        if self.local:
+            return self._log_span_local(payload)
+        resp = self._http.post("/api/spans", json=payload, headers=self._headers())
+        resp.raise_for_status()
+        return resp.json()
+
+    def register_prompt(
+        self,
+        name: str,
+        content: str,
+        description: Optional[str] = None,
+        metadata: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        project_id = self._require_project()
+        payload = {
+            "project_id": project_id,
+            "name": name,
+            "description": description,
+            "content": content,
+            "metadata": metadata,
+        }
+        if self.local:
+            return self._register_prompt_local(payload)
+        resp = self._http.post("/api/prompts", json=payload, headers=self._headers())
+        resp.raise_for_status()
+        return resp.json()
+
+    def create_prompt_version(
+        self, prompt_id: str, content: str, metadata: Optional[dict[str, Any]] = None
+    ) -> dict[str, Any]:
+        payload = {"content": content, "metadata": metadata}
+        if self.local:
+            return self._create_prompt_version_local(prompt_id, payload)
+        resp = self._http.post(f"/api/prompts/{prompt_id}/versions", json=payload, headers=self._headers())
+        resp.raise_for_status()
+        return resp.json()
+
+    def _require_project(self) -> str:
+        if not self.project_id:
+            raise ValueError("project_id is required")
+        return self.project_id
+
+    # Local mode helpers (direct DB writes) ---------------------------------
+    def _log_run_local(self, payload: dict[str, Any]) -> dict[str, Any]:
+        db = SessionLocal()
+        try:
+            run = Run(
+                project_id=payload["project_id"],
+                prompt_version_id=payload.get("prompt_version_id"),
+                name=payload.get("name"),
+                input_text=payload.get("input_text"),
+                output_text=payload.get("output_text"),
+                token_input=(payload.get("token_usage") or {}).get("prompt"),
+                token_output=(payload.get("token_usage") or {}).get("completion"),
+                cost=payload.get("cost"),
+                latency_ms=payload.get("latency_ms"),
+                error=payload.get("error"),
+                metadata_=payload.get("metadata"),
+            )
+            db.add(run)
+            db.commit()
+            db.refresh(run)
+            return {
+                "id": run.id,
+                "project_id": run.project_id,
+                "prompt_version_id": run.prompt_version_id,
+                "name": run.name,
+                "input_text": run.input_text,
+                "output_text": run.output_text,
+                "token_input": run.token_input,
+                "token_output": run.token_output,
+                "cost": run.cost,
+                "latency_ms": run.latency_ms,
+                "error": run.error,
+                "metadata": run.metadata_,
+                "created_at": run.created_at.isoformat(),
+            }
+        finally:
+            db.close()
+
+    def _log_span_local(self, payload: dict[str, Any]) -> dict[str, Any]:
+        db = SessionLocal()
+        try:
+            start_time = payload.get("start_time")
+            end_time = payload.get("end_time")
+            if isinstance(start_time, str):
+                try:
+                    from datetime import datetime
+
+                    start_time = datetime.fromisoformat(start_time)
+                except Exception:
+                    start_time = None
+            if isinstance(end_time, str):
+                try:
+                    from datetime import datetime
+
+                    end_time = datetime.fromisoformat(end_time)
+                except Exception:
+                    end_time = None
+            span = Span(
+                project_id=payload["project_id"],
+                run_id=payload["run_id"],
+                parent_id=payload.get("parent_id"),
+                name=payload["name"],
+                start_time=start_time or None,
+                end_time=end_time or None,
+                latency_ms=payload.get("latency_ms"),
+                metadata_=payload.get("metadata"),
+            )
+            db.add(span)
+            db.commit()
+            db.refresh(span)
+            return {
+                "id": span.id,
+                "project_id": span.project_id,
+                "run_id": span.run_id,
+                "parent_id": span.parent_id,
+                "name": span.name,
+                "start_time": span.start_time.isoformat(),
+                "end_time": span.end_time.isoformat() if span.end_time else None,
+                "latency_ms": span.latency_ms,
+                "metadata": span.metadata_,
+            }
+        finally:
+            db.close()
+
+    def _register_prompt_local(self, payload: dict[str, Any]) -> dict[str, Any]:
+        db = SessionLocal()
+        try:
+            prompt = Prompt(
+                project_id=payload["project_id"],
+                name=payload["name"],
+                description=payload.get("description"),
+            )
+            db.add(prompt)
+            db.commit()
+            db.refresh(prompt)
+            version = PromptVersion(
+                prompt_id=prompt.id,
+                version=1,
+                content=payload["content"],
+                metadata_=payload.get("metadata"),
+            )
+            db.add(version)
+            db.commit()
+            return {
+                "id": prompt.id,
+                "project_id": prompt.project_id,
+                "name": prompt.name,
+                "description": prompt.description,
+                "created_at": prompt.created_at.isoformat(),
+            }
+        finally:
+            db.close()
+
+    def _create_prompt_version_local(self, prompt_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+        db = SessionLocal()
+        try:
+            latest = (
+                db.query(PromptVersion).filter(PromptVersion.prompt_id == prompt_id).order_by(PromptVersion.version.desc()).first()
+            )
+            next_version = (latest.version + 1) if latest else 1
+            version = PromptVersion(
+                prompt_id=prompt_id,
+                version=next_version,
+                content=payload["content"],
+                metadata_=payload.get("metadata"),
+            )
+            db.add(version)
+            db.commit()
+            db.refresh(version)
+            return {
+                "id": version.id,
+                "prompt_id": version.prompt_id,
+                "version": version.version,
+                "content": version.content,
+                "metadata": version.metadata_,
+                "created_at": version.created_at.isoformat(),
+            }
+        finally:
+            db.close()
+
+
+def timed(func):
+    def wrapper(*args, **kwargs):
+        start = time.perf_counter()
+        result = func(*args, **kwargs)
+        elapsed = (time.perf_counter() - start) * 1000
+        return result, elapsed
+
+    return wrapper

agentgear/sdk/decorators.py

@@ -0,0 +1,65 @@
+import functools
+import json
+import time
+from typing import Any, Callable, Optional
+
+from agentgear.sdk.client import AgentGearClient
+
+
+def observe(
+    client: AgentGearClient,
+    name: Optional[str] = None,
+    prompt_version_id: Optional[str] = None,
+    metadata: Optional[dict[str, Any]] = None,
+):
+    """
+    Decorator to capture function inputs/outputs and log a run.
+    """
+
+    def decorator(func: Callable):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            start = time.perf_counter()
+            error_text = None
+            output_text = None
+            try:
+                result = func(*args, **kwargs)
+                output_text = _safe_string(result)
+                return result
+            except Exception as exc:  # noqa: BLE001
+                error_text = str(exc)
+                raise
+            finally:
+                elapsed_ms = (time.perf_counter() - start) * 1000
+                input_repr = _inputs_to_string(args, kwargs)
+                try:
+                    client.log_run(
+                        name=name or func.__name__,
+                        input_text=input_repr,
+                        output_text=output_text,
+                        prompt_version_id=prompt_version_id,
+                        latency_ms=elapsed_ms,
+                        error=error_text,
+                        metadata=metadata,
+                    )
+                except Exception:
+                    # Do not break caller; best-effort logging.
+                    pass
+
+        return wrapper
+
+    return decorator
+
+
+def _inputs_to_string(args, kwargs) -> str:
+    try:
+        return json.dumps({"args": args, "kwargs": kwargs}, default=str)
+    except Exception:
+        return f"args={args}, kwargs={kwargs}"
+
+
+def _safe_string(value: Any) -> str:
+    try:
+        return json.dumps(value, default=str)
+    except Exception:
+        return str(value)

agentgear/sdk/integrations/openai.py

@@ -0,0 +1,52 @@
+from typing import Any, Dict, Optional
+
+from agentgear.sdk.client import AgentGearClient
+
+
+def instrument_openai_chat(
+    openai_client: Any,
+    agentgear: AgentGearClient,
+    model: str,
+    prompt_version_id: Optional[str] = None,
+):
+    """
+    Wraps OpenAI chat completions to automatically log runs.
+    """
+
+    original = openai_client.chat.completions.create
+
+    def wrapped(**kwargs):
+        messages = kwargs.get("messages")
+        input_text = str(messages)
+        response = original(**kwargs)
+        output_text = _response_text(response)
+
+        usage = getattr(response, "usage", None) or {}
+        token_usage = {
+            "prompt": getattr(usage, "prompt_tokens", None) or usage.get("prompt_tokens"),
+            "completion": getattr(usage, "completion_tokens", None) or usage.get("completion_tokens"),
+            "total": getattr(usage, "total_tokens", None) or usage.get("total_tokens"),
+        }
+        agentgear.log_run(
+            name=f"openai:{model}",
+            input_text=input_text,
+            output_text=output_text,
+            prompt_version_id=prompt_version_id,
+            token_usage=token_usage,
+            latency_ms=None,
+        )
+        return response
+
+    openai_client.chat.completions.create = wrapped
+    return openai_client
+
+
+def _response_text(response: Any) -> str:
+    try:
+        if hasattr(response, "choices") and response.choices:
+            content = getattr(response.choices[0].message, "content", None)
+            if content:
+                return content
+        return str(response)
+    except Exception:
+        return str(response)

agentgear/sdk/prompt.py

@@ -0,0 +1,23 @@
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+from jinja2 import Template
+
+
+@dataclass
+class Prompt:
+    name: str
+    template: str
+    version_id: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+    def render(self, **kwargs) -> str:
+        return Template(self.template).render(**kwargs)
+
+    def with_version(self, version_id: str) -> "Prompt":
+        return Prompt(
+            name=self.name,
+            template=self.template,
+            version_id=version_id,
+            metadata=self.metadata,
+        )

agentgear/sdk/trace.py

@@ -0,0 +1,59 @@
+import time
+from typing import Any, Optional
+
+from agentgear.sdk.client import AgentGearClient
+
+
+class trace:
+    """
+    Context manager for recording spans.
+    Usage:
+        with trace(client, run_id, name="step"):
+            ...
+    """
+
+    def __init__(
+        self,
+        client: AgentGearClient,
+        run_id: str,
+        name: str,
+        parent_id: Optional[str] = None,
+        metadata: Optional[dict[str, Any]] = None,
+    ):
+        self.client = client
+        self.run_id = run_id
+        self.name = name
+        self.parent_id = parent_id
+        self.metadata = metadata
+        self.span_id: Optional[str] = None
+        self._start = None
+
+    def __enter__(self):
+        self._start = time.perf_counter()
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        latency_ms = (time.perf_counter() - self._start) * 1000 if self._start else None
+        try:
+            span = self.client.log_span(
+                run_id=self.run_id,
+                name=self.name,
+                parent_id=self.parent_id,
+                latency_ms=latency_ms,
+                metadata=self.metadata,
+            )
+            self.span_id = span.get("id")
+        except Exception:
+            # Best-effort
+            pass
+        return False
+
+    def child(self, name: str, metadata: Optional[dict[str, Any]] = None) -> "trace":
+        """Create a child span context."""
+        return trace(
+            client=self.client,
+            run_id=self.run_id,
+            name=name,
+            parent_id=self.span_id or self.parent_id,
+            metadata=metadata,
+        )

agentgear/server/__init__.py

@@ -0,0 +1 @@
+# AgentGear server package

agentgear/server/app/__init__.py

@@ -0,0 +1 @@
+# AgentGear FastAPI application package

agentgear/server/app/api/__init__.py

@@ -0,0 +1 @@
+# API package marker