playagent 0.1.0__py3-none-any.whl

playagent/__init__.py

@@ -0,0 +1,61 @@
+"""Public API surface for PlayAgent."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def _maybe_print_welcome() -> None:
+    """Print a one-time welcome message and initialize DB on first import."""
+    import os
+
+    playagent_dir = Path.home() / ".playagent"
+    if playagent_dir.exists() or os.environ.get("PLAYAGENT_NO_WELCOME"):
+        return
+    try:
+        playagent_dir.mkdir(parents=True, exist_ok=True)
+        print(  # noqa: T201
+            f"PlayAgent v0.1.0 — creating local database at {playagent_dir / 'db.sqlite'}"
+        )
+        from playagent.storage import get_db_path, init_db
+
+        init_db(get_db_path())
+    except Exception:  # noqa: BLE001
+        pass  # Never crash on welcome message
+
+
+_maybe_print_welcome()
+
+from playagent.assertions import (  # noqa: E402
+    AssertionFailedError,
+    assert_trace,
+    contains,
+    equals,
+    matches,
+    starts_with,
+)
+from playagent.classifier import classify_trace, evaluate, score_goal  # noqa: E402
+from playagent.core import get_current_session_id, record, trace, validate_environment  # noqa: E402
+from playagent.models import ClassificationResult, Session, ToolCall, TraceEvent  # noqa: E402
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "record",
+    "trace",
+    "get_current_session_id",
+    "validate_environment",
+    "assert_trace",
+    "contains",
+    "starts_with",
+    "matches",
+    "equals",
+    "AssertionFailedError",
+    "classify_trace",
+    "score_goal",
+    "evaluate",
+    "Session",
+    "TraceEvent",
+    "ToolCall",
+    "ClassificationResult",
+]

playagent/adapters/anthropic.py

@@ -0,0 +1,293 @@
+"""Anthropic drop-in adapters that capture request/response traces into PlayAgent storage."""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Callable
+from typing import Any
+
+try:
+    import anthropic
+except ImportError as exc:  # pragma: no cover
+    # Scenario: user did `pip install playagent` without the anthropic extra.
+    raise ImportError(
+        "Anthropic adapter requires the anthropic package. "
+        "Install it with: pip install playagent[anthropic]"
+    ) from exc
+
+from playagent.core import get_current_session_id
+from playagent.models import Session, ToolCall, TraceEvent, generate_id, now_utc
+from playagent.storage import get_turn_count, save_session, save_trace_event, update_session
+
+
+def _create_standalone_session() -> Session | None:
+    """Create and persist a standalone session when no active trace session exists."""
+    try:
+        started_at = now_utc()
+        session = Session(
+            id=generate_id("sess"),
+            agent_name="standalone",
+            status="running",
+            started_at=started_at,
+            ended_at=None,
+            metadata={},
+            error=None,
+            classification=None,
+        )
+        save_session(session)
+        return session
+    except Exception as exc:  # noqa: BLE001
+        logging.warning("PlayAgent failed to create standalone session: %s", exc)
+        return None
+
+
+def _finalize_standalone_session(
+    session: Session | None, status: str, error: str | None = None
+) -> None:
+    """Mark standalone sessions complete so lifecycle mirrors decorator-based sessions."""
+    if session is None:
+        return
+    try:
+        session.status = status
+        session.error = error
+        session.ended_at = now_utc()
+        update_session(session)
+    except Exception as exc:  # noqa: BLE001
+        logging.warning("PlayAgent failed to finalize standalone session: %s", exc)
+
+
+def _resolve_session() -> tuple[str | None, Session | None]:
+    """Return active session id, creating standalone session if needed."""
+    session_id = get_current_session_id()
+    if session_id is not None:
+        return session_id, None
+
+    standalone = _create_standalone_session()
+    if standalone is None:
+        return None, None
+    return standalone.id, standalone
+
+
+def _extract_response_content(content_blocks: Any) -> str:
+    """Extract the first text block from Anthropic content blocks."""
+    if not content_blocks:
+        return ""
+    for block in content_blocks:
+        if getattr(block, "type", None) == "text":
+            return str(getattr(block, "text", "") or "")
+    return ""
+
+
+def _extract_tool_calls(content_blocks: Any) -> list[ToolCall]:
+    """Extract tool_use blocks from Anthropic content blocks."""
+    calls: list[ToolCall] = []
+    if not content_blocks:
+        return calls
+
+    for block in content_blocks:
+        if getattr(block, "type", None) != "tool_use":
+            continue
+        block_input = getattr(block, "input", None)
+        args = block_input if isinstance(block_input, dict) else {}
+        calls.append(
+            ToolCall(
+                name=str(getattr(block, "name", "") or ""),
+                arguments=args,
+                result=None,
+                call_id=getattr(block, "id", None),
+            )
+        )
+    return calls
+
+
+def _map_finish_reason(stop_reason: str | None) -> str:
+    """Map Anthropic stop reasons into unified TraceEvent finish reasons."""
+    if stop_reason == "end_turn":
+        return "stop"
+    if stop_reason == "tool_use":
+        return "tool_calls"
+    return str(stop_reason or "stop")
+
+
+def _safe_save_event(event: TraceEvent) -> None:
+    """Persist trace event without surfacing instrumentation failures."""
+    try:
+        save_trace_event(event)
+    except Exception as exc:  # noqa: BLE001
+        logging.warning("PlayAgent failed to save Anthropic trace event %s: %s", event.id, exc)
+
+
+def _extract_model_and_messages(kwargs: dict[str, Any]) -> tuple[str, list[dict[str, Any]]]:
+    model = str(kwargs.get("model") or "")
+    messages_raw = kwargs.get("messages") or []
+    if isinstance(messages_raw, list):
+        messages = messages_raw
+    else:
+        messages = []
+    return model, messages
+
+
+def _build_success_event(
+    *,
+    session_id: str,
+    model: str,
+    messages: list[dict[str, Any]],
+    response: Any,
+    latency_ms: int,
+) -> TraceEvent:
+    content = getattr(response, "content", None)
+    usage = getattr(response, "usage", None)
+
+    response_content = _extract_response_content(content)
+    tool_calls = _extract_tool_calls(content)
+    prompt_tokens = int(getattr(usage, "input_tokens", 0) or 0)
+    completion_tokens = int(getattr(usage, "output_tokens", 0) or 0)
+    finish_reason = _map_finish_reason(getattr(response, "stop_reason", None))
+
+    turn = get_turn_count(session_id) + 1
+    return TraceEvent(
+        id=generate_id("evt"),
+        session_id=session_id,
+        turn=turn,
+        model=model,
+        provider="anthropic",
+        messages=messages,
+        response_content=response_content,
+        tool_calls=tool_calls,
+        prompt_tokens=prompt_tokens,
+        completion_tokens=completion_tokens,
+        finish_reason=finish_reason,
+        latency_ms=latency_ms,
+        error=None,
+        created_at=now_utc(),
+    )
+
+
+def _build_error_event(
+    *,
+    session_id: str,
+    model: str,
+    messages: list[dict[str, Any]],
+    error: Exception,
+    latency_ms: int,
+) -> TraceEvent:
+    turn = get_turn_count(session_id) + 1
+    return TraceEvent(
+        id=generate_id("evt"),
+        session_id=session_id,
+        turn=turn,
+        model=model,
+        provider="anthropic",
+        messages=messages,
+        response_content="",
+        tool_calls=[],
+        prompt_tokens=0,
+        completion_tokens=0,
+        finish_reason="error",
+        latency_ms=latency_ms,
+        error=str(error),
+        created_at=now_utc(),
+    )
+
+
+def _instrument_sync_create(original_create: Callable[..., Any]) -> Callable[..., Any]:
+    def wrapped_create(*args: Any, **kwargs: Any) -> Any:
+        start = time.monotonic()
+        model, messages = _extract_model_and_messages(kwargs)
+        session_id, standalone_session = _resolve_session()
+
+        try:
+            response = original_create(*args, **kwargs)
+        except Exception as error:
+            latency_ms = int((time.monotonic() - start) * 1000)
+            if session_id is not None:
+                error_event = _build_error_event(
+                    session_id=session_id,
+                    model=model,
+                    messages=messages,
+                    error=error,
+                    latency_ms=latency_ms,
+                )
+                _safe_save_event(error_event)
+            _finalize_standalone_session(standalone_session, status="failed", error=str(error))
+            raise
+
+        latency_ms = int((time.monotonic() - start) * 1000)
+        if session_id is not None:
+            try:
+                response_model = str(getattr(response, "model", None) or model)
+                event = _build_success_event(
+                    session_id=session_id,
+                    model=response_model,
+                    messages=messages,
+                    response=response,
+                    latency_ms=latency_ms,
+                )
+                _safe_save_event(event)
+            except Exception as exc:  # noqa: BLE001
+                logging.warning("PlayAgent failed to instrument Anthropic response: %s", exc)
+
+        _finalize_standalone_session(standalone_session, status="passed", error=None)
+        return response
+
+    return wrapped_create
+
+
+def _instrument_async_create(original_create: Callable[..., Any]) -> Callable[..., Any]:
+    async def wrapped_create(*args: Any, **kwargs: Any) -> Any:
+        start = time.monotonic()
+        model, messages = _extract_model_and_messages(kwargs)
+        session_id, standalone_session = _resolve_session()
+
+        try:
+            response = await original_create(*args, **kwargs)
+        except Exception as error:
+            latency_ms = int((time.monotonic() - start) * 1000)
+            if session_id is not None:
+                error_event = _build_error_event(
+                    session_id=session_id,
+                    model=model,
+                    messages=messages,
+                    error=error,
+                    latency_ms=latency_ms,
+                )
+                _safe_save_event(error_event)
+            _finalize_standalone_session(standalone_session, status="failed", error=str(error))
+            raise
+
+        latency_ms = int((time.monotonic() - start) * 1000)
+        if session_id is not None:
+            try:
+                response_model = str(getattr(response, "model", None) or model)
+                event = _build_success_event(
+                    session_id=session_id,
+                    model=response_model,
+                    messages=messages,
+                    response=response,
+                    latency_ms=latency_ms,
+                )
+                _safe_save_event(event)
+            except Exception as exc:  # noqa: BLE001
+                logging.warning("PlayAgent failed to instrument Anthropic async response: %s", exc)
+
+        _finalize_standalone_session(standalone_session, status="passed", error=None)
+        return response
+
+    return wrapped_create
+
+
+class Anthropic(anthropic.Anthropic):
+    """Drop-in Anthropic client with automatic trace persistence."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.messages.create = _instrument_sync_create(self.messages.create)
+
+
+class AsyncAnthropic(anthropic.AsyncAnthropic):
+    """Async drop-in Anthropic client with automatic trace persistence."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.messages.create = _instrument_async_create(self.messages.create)

playagent/adapters/openai.py

@@ -0,0 +1,282 @@
+"""OpenAI drop-in adapters that capture request/response traces into PlayAgent storage."""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from collections.abc import Callable
+from typing import Any
+
+try:
+    import openai
+except ImportError as exc:  # pragma: no cover
+    # Scenario: user did `pip install playagent` without the openai extra.
+    raise ImportError(
+        "OpenAI adapter requires the openai package. Install it with: pip install playagent[openai]"
+    ) from exc
+
+from playagent.core import get_current_session_id
+from playagent.models import Session, ToolCall, TraceEvent, generate_id, now_utc
+from playagent.storage import get_turn_count, save_session, save_trace_event, update_session
+
+
+def _create_standalone_session() -> Session | None:
+    """Create and persist a standalone session when no active trace session exists."""
+    try:
+        started_at = now_utc()
+        session = Session(
+            id=generate_id("sess"),
+            agent_name="standalone",
+            status="running",
+            started_at=started_at,
+            ended_at=None,
+            metadata={},
+            error=None,
+            classification=None,
+        )
+        save_session(session)
+        return session
+    except Exception as exc:  # noqa: BLE001
+        logging.warning("PlayAgent failed to create standalone session: %s", exc)
+        return None
+
+
+def _parse_tool_calls(raw_tool_calls: Any) -> list[ToolCall]:
+    """Convert OpenAI tool call payloads into PlayAgent ToolCall models."""
+    parsed: list[ToolCall] = []
+    if not raw_tool_calls:
+        return parsed
+
+    for call in raw_tool_calls:
+        try:
+            args = json.loads(call.function.arguments) if call.function.arguments else {}
+        except Exception:  # noqa: BLE001
+            args = {}
+        parsed.append(
+            ToolCall(
+                name=getattr(call.function, "name", ""),
+                arguments=args,
+                result=None,
+                call_id=getattr(call, "id", None),
+            )
+        )
+    return parsed
+
+
+def _finalize_standalone_session(
+    session: Session | None, status: str, error: str | None = None
+) -> None:
+    """Mark standalone sessions complete so lifecycle mirrors decorator-based sessions."""
+    if session is None:
+        return
+    try:
+        session.status = status
+        session.error = error
+        session.ended_at = now_utc()
+        update_session(session)
+    except Exception as exc:  # noqa: BLE001
+        logging.warning("PlayAgent failed to finalize standalone session: %s", exc)
+
+
+def _resolve_session() -> tuple[str | None, Session | None]:
+    """Return active session id, creating standalone session if needed."""
+    session_id = get_current_session_id()
+    if session_id is not None:
+        return session_id, None
+
+    standalone = _create_standalone_session()
+    if standalone is None:
+        return None, None
+    return standalone.id, standalone
+
+
+def _build_event_from_response(
+    *,
+    session_id: str,
+    model: str,
+    messages: list[dict[str, Any]],
+    response: Any,
+    latency_ms: int,
+) -> TraceEvent:
+    """Build TraceEvent from successful OpenAI API response."""
+    choice0 = response.choices[0] if getattr(response, "choices", None) else None
+    message = choice0.message if choice0 is not None else None
+    usage = getattr(response, "usage", None)
+
+    response_content = getattr(message, "content", "") if message is not None else ""
+    parsed_tool_calls = _parse_tool_calls(getattr(message, "tool_calls", None) if message else None)
+    prompt_tokens = int(getattr(usage, "prompt_tokens", 0) or 0)
+    completion_tokens = int(getattr(usage, "completion_tokens", 0) or 0)
+    finish_reason = getattr(choice0, "finish_reason", "stop") if choice0 is not None else "stop"
+
+    turn = get_turn_count(session_id) + 1
+
+    return TraceEvent(
+        id=generate_id("evt"),
+        session_id=session_id,
+        turn=turn,
+        model=model,
+        provider="openai",
+        messages=messages,
+        response_content=response_content or "",
+        tool_calls=parsed_tool_calls,
+        prompt_tokens=prompt_tokens,
+        completion_tokens=completion_tokens,
+        finish_reason=finish_reason or "stop",
+        latency_ms=latency_ms,
+        error=None,
+        created_at=now_utc(),
+    )
+
+
+def _build_event_from_error(
+    *,
+    session_id: str,
+    model: str,
+    messages: list[dict[str, Any]],
+    error: Exception,
+    latency_ms: int,
+) -> TraceEvent:
+    """Build TraceEvent from failed OpenAI API call."""
+    turn = get_turn_count(session_id) + 1
+    return TraceEvent(
+        id=generate_id("evt"),
+        session_id=session_id,
+        turn=turn,
+        model=model,
+        provider="openai",
+        messages=messages,
+        response_content="",
+        tool_calls=[],
+        prompt_tokens=0,
+        completion_tokens=0,
+        finish_reason="error",
+        latency_ms=latency_ms,
+        error=str(error),
+        created_at=now_utc(),
+    )
+
+
+def _safe_save_event(event: TraceEvent) -> None:
+    """Persist trace event without surfacing instrumentation failures."""
+    try:
+        save_trace_event(event)
+    except Exception as exc:  # noqa: BLE001
+        logging.warning("PlayAgent failed to save OpenAI trace event %s: %s", event.id, exc)
+
+
+def _extract_model_and_messages(kwargs: dict[str, Any]) -> tuple[str, list[dict[str, Any]]]:
+    model = str(kwargs.get("model") or "")
+    messages_raw = kwargs.get("messages") or []
+    if isinstance(messages_raw, list):
+        messages = messages_raw
+    else:
+        messages = []
+    return model, messages
+
+
+def _instrument_sync_create(original_create: Callable[..., Any]) -> Callable[..., Any]:
+    def wrapped_create(*args: Any, **kwargs: Any) -> Any:
+        start = time.monotonic()
+        model, messages = _extract_model_and_messages(kwargs)
+        session_id, standalone_session = _resolve_session()
+
+        try:
+            response = original_create(*args, **kwargs)
+        except Exception as error:
+            latency_ms = int((time.monotonic() - start) * 1000)
+            if session_id is not None:
+                error_event = _build_event_from_error(
+                    session_id=session_id,
+                    model=model,
+                    messages=messages,
+                    error=error,
+                    latency_ms=latency_ms,
+                )
+                _safe_save_event(error_event)
+            _finalize_standalone_session(standalone_session, status="failed", error=str(error))
+            raise
+
+        latency_ms = int((time.monotonic() - start) * 1000)
+        if session_id is not None:
+            try:
+                response_model = str(getattr(response, "model", None) or model)
+                success_event = _build_event_from_response(
+                    session_id=session_id,
+                    model=response_model,
+                    messages=messages,
+                    response=response,
+                    latency_ms=latency_ms,
+                )
+                _safe_save_event(success_event)
+            except Exception as exc:  # noqa: BLE001
+                logging.warning("PlayAgent failed to instrument OpenAI response: %s", exc)
+
+        _finalize_standalone_session(standalone_session, status="passed", error=None)
+        return response
+
+    return wrapped_create
+
+
+def _instrument_async_create(original_create: Callable[..., Any]) -> Callable[..., Any]:
+    async def wrapped_create(*args: Any, **kwargs: Any) -> Any:
+        start = time.monotonic()
+        model, messages = _extract_model_and_messages(kwargs)
+        session_id, standalone_session = _resolve_session()
+
+        try:
+            response = await original_create(*args, **kwargs)
+        except Exception as error:
+            latency_ms = int((time.monotonic() - start) * 1000)
+            if session_id is not None:
+                error_event = _build_event_from_error(
+                    session_id=session_id,
+                    model=model,
+                    messages=messages,
+                    error=error,
+                    latency_ms=latency_ms,
+                )
+                _safe_save_event(error_event)
+            _finalize_standalone_session(standalone_session, status="failed", error=str(error))
+            raise
+
+        latency_ms = int((time.monotonic() - start) * 1000)
+        if session_id is not None:
+            try:
+                response_model = str(getattr(response, "model", None) or model)
+                success_event = _build_event_from_response(
+                    session_id=session_id,
+                    model=response_model,
+                    messages=messages,
+                    response=response,
+                    latency_ms=latency_ms,
+                )
+                _safe_save_event(success_event)
+            except Exception as exc:  # noqa: BLE001
+                logging.warning("PlayAgent failed to instrument OpenAI async response: %s", exc)
+
+        _finalize_standalone_session(standalone_session, status="passed", error=None)
+        return response
+
+    return wrapped_create
+
+
+class OpenAI(openai.OpenAI):
+    """Drop-in OpenAI client with automatic trace persistence."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.chat.completions.create = _instrument_sync_create(self.chat.completions.create)
+        if hasattr(self.chat.completions, "acreate"):
+            self.chat.completions.acreate = _instrument_async_create(self.chat.completions.acreate)
+
+
+class AsyncOpenAI(openai.AsyncOpenAI):
+    """Async drop-in OpenAI client with automatic trace persistence."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.chat.completions.create = _instrument_async_create(self.chat.completions.create)
+        if hasattr(self.chat.completions, "acreate"):
+            self.chat.completions.acreate = _instrument_async_create(self.chat.completions.acreate)