specops-ai 0.2.0__py3-none-any.whl

specops_ai/__init__.py

@@ -0,0 +1,124 @@
+"""SpecOps — Agent Reliability Kit."""
+
+__version__ = "0.2.0"
+
+from specops_ai.adapters import BaseAdapter, PlainAdapter, get_adapter, register_adapter
+from specops_ai.config import configure, get_tracer, reset
+from specops_ai.coordinate import (
+    AgentOutput,
+    BehaviorTrace,
+    CoordinationIssue,
+    CoordinationResult,
+    MemorySnapshot,
+    check_consensus,
+    check_divergence,
+    check_memory_integrity,
+)
+from specops_ai.eval import (
+    EvalCase,
+    EvalResult,
+    JudgeVerdict,
+    eval_golden_set,
+    eval_golden_set_async,
+    llm_judge,
+    llm_judge_async,
+)
+from specops_ai.heal import (
+    EscalatePolicy,
+    FallbackPolicy,
+    HealingChain,
+    PolicyAction,
+    PolicyResult,
+    PruneMemoryPolicy,
+    RetryPolicy,
+    self_healing,
+)
+from specops_ai.rca import RCAEdge, RCAGraph, RCANode, build_rca_graph
+from specops_ai.replay import (
+    RecordedCall,
+    ReplayMismatchError,
+    ReplaySession,
+    ReplayStore,
+    recording,
+    replayable,
+    replaying,
+)
+from specops_ai.simulate import (
+    AnomalyType,
+    SimEvent,
+    SimResult,
+    SimulationBudgetExceeded,
+    SimulationEnvironment,
+    get_current_simulation,
+    simulate,
+    simulation,
+)
+from specops_ai.trace import trace_agent, trace_llm, trace_tool
+from specops_ai.viz import save_dot, to_dot
+
+__all__ = [
+    # Adapters
+    "BaseAdapter",
+    "PlainAdapter",
+    "get_adapter",
+    "register_adapter",
+    # Config
+    "configure",
+    "get_tracer",
+    "reset",
+    # Tracing
+    "trace_agent",
+    "trace_llm",
+    "trace_tool",
+    # Replay
+    "RecordedCall",
+    "ReplayMismatchError",
+    "ReplaySession",
+    "ReplayStore",
+    "recording",
+    "replayable",
+    "replaying",
+    # Eval
+    "EvalCase",
+    "EvalResult",
+    "JudgeVerdict",
+    "eval_golden_set",
+    "eval_golden_set_async",
+    "llm_judge",
+    "llm_judge_async",
+    # Heal
+    "EscalatePolicy",
+    "FallbackPolicy",
+    "HealingChain",
+    "PolicyAction",
+    "PolicyResult",
+    "PruneMemoryPolicy",
+    "RetryPolicy",
+    "self_healing",
+    # RCA
+    "RCAEdge",
+    "RCAGraph",
+    "RCANode",
+    "build_rca_graph",
+    # Viz
+    "save_dot",
+    "to_dot",
+    # Simulation
+    "AnomalyType",
+    "SimEvent",
+    "SimResult",
+    "SimulationBudgetExceeded",
+    "SimulationEnvironment",
+    "get_current_simulation",
+    "simulate",
+    "simulation",
+    # Coordination
+    "AgentOutput",
+    "BehaviorTrace",
+    "CoordinationIssue",
+    "CoordinationResult",
+    "MemorySnapshot",
+    "check_consensus",
+    "check_divergence",
+    "check_memory_integrity",
+]

specops_ai/_constants.py

@@ -0,0 +1,33 @@
+"""Semantic attribute keys for SpecOps OTel spans."""
+
+# Agent
+AGENT_NAME = "specops.agent.name"
+AGENT_TASK = "specops.agent.task"
+AGENT_FRAMEWORK = "specops.agent.framework"
+AGENT_STEP = "specops.agent.step"
+AGENT_DECISION = "specops.agent.decision"
+
+# Tool
+TOOL_NAME = "specops.tool.name"
+TOOL_ARGS = "specops.tool.args"
+TOOL_RESULT = "specops.tool.result"
+
+# LLM
+LLM_MODEL = "specops.llm.model"
+LLM_PROVIDER = "specops.llm.provider"
+LLM_TOKENS_INPUT = "specops.llm.tokens.input"
+LLM_TOKENS_OUTPUT = "specops.llm.tokens.output"
+LLM_TEMPERATURE = "specops.llm.temperature"
+LLM_SEED = "specops.llm.seed"
+LLM_RESULT = "specops.llm.result"
+
+# Coordination / multi-agent
+COORDINATION_EVENT = "specops.coordination.event"
+MEMORY_ACCESS = "specops.memory.access"
+
+# Replay
+REPLAY_SEED = "specops.replay.seed"
+REPLAY_SESSION_ID = "specops.replay.session_id"
+
+# Limits
+MAX_ATTR_LENGTH = 1024

specops_ai/_context.py

@@ -0,0 +1,21 @@
+"""Context propagation utilities for SpecOps tracing."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+
+from opentelemetry.context import Context
+
+_current_agent_ctx: ContextVar[Context | None] = ContextVar(
+    "specops_agent_ctx", default=None
+)
+
+
+def get_current_context() -> Context | None:
+    """Return the active SpecOps trace context."""
+    return _current_agent_ctx.get()
+
+
+def set_current_context(ctx: Context) -> Token[Context | None]:
+    """Set the active context. Returns a token for reset."""
+    return _current_agent_ctx.set(ctx)

specops_ai/adapters/__init__.py

@@ -0,0 +1,102 @@
+"""Framework adapters for SpecOps tracing."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class BaseAdapter(ABC):
+    """Base class for framework adapters.
+
+    Adapters normalize framework-specific metadata into SpecOps semantic attributes.
+    """
+
+    @abstractmethod
+    def extract_task(self, args: tuple[Any, ...], kwargs: dict[str, Any]) -> str:
+        """Extract the agent task from function arguments."""
+
+    @abstractmethod
+    def extract_llm_metadata(self, result: Any) -> dict[str, Any]:
+        """Extract LLM metadata (tokens, model) from a call result."""
+
+    @abstractmethod
+    def extract_tool_metadata(
+        self, args: tuple[Any, ...], kwargs: dict[str, Any], result: Any
+    ) -> dict[str, Any]:
+        """Extract tool metadata from a call."""
+
+
+class PlainAdapter(BaseAdapter):
+    """Default adapter for plain Python agent code.
+
+    Assumes:
+    - First positional arg is the task string.
+    - LLM results are dicts with `model`, `input_tokens`, `output_tokens`.
+    - Tool results are returned directly.
+    """
+
+    def extract_task(self, args: tuple[Any, ...], kwargs: dict[str, Any]) -> str:
+        """First positional arg or 'task' kwarg."""
+        if args:
+            return str(args[0])
+        return str(kwargs.get("task", ""))
+
+    def extract_llm_metadata(self, result: Any) -> dict[str, Any]:
+        """Extract from dict result."""
+        if isinstance(result, dict):
+            return {
+                k: v
+                for k, v in result.items()
+                if k in ("model", "input_tokens", "output_tokens")
+            }
+        return {}
+
+    def extract_tool_metadata(
+        self, args: tuple[Any, ...], kwargs: dict[str, Any], result: Any
+    ) -> dict[str, Any]:
+        """Return args and result as metadata."""
+        return {"args": args, "kwargs": kwargs, "result": result}
+
+
+_ADAPTERS: dict[str, type[BaseAdapter]] = {
+    "plain": PlainAdapter,
+}
+
+
+def get_adapter(framework: str) -> BaseAdapter:
+    """Get an adapter instance by framework name."""
+    cls = _ADAPTERS.get(framework, PlainAdapter)
+    return cls()
+
+
+def register_adapter(framework: str, adapter_cls: type[BaseAdapter]) -> None:
+    """Register a custom adapter for a framework."""
+    _ADAPTERS[framework] = adapter_cls
+
+
+def _auto_register() -> None:
+    """Auto-register framework adapters if their libraries are available."""
+    try:
+        from specops_ai.adapters.langgraph import LangGraphAdapter
+
+        _ADAPTERS.setdefault("langgraph", LangGraphAdapter)
+    except ImportError:
+        pass
+
+    try:
+        from specops_ai.adapters.crewai import CrewAIAdapter
+
+        _ADAPTERS.setdefault("crewai", CrewAIAdapter)
+    except ImportError:
+        pass
+
+    try:
+        from specops_ai.adapters.autogen import AutoGenAdapter
+
+        _ADAPTERS.setdefault("autogen", AutoGenAdapter)
+    except ImportError:
+        pass
+
+
+_auto_register()

specops_ai/adapters/autogen.py

@@ -0,0 +1,57 @@
+"""AutoGen adapter for SpecOps tracing.
+
+Stub implementation for Microsoft AutoGen's multi-agent chat patterns.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from specops_ai.adapters import BaseAdapter
+
+
+class AutoGenAdapter(BaseAdapter):
+    """Adapter for Microsoft AutoGen framework (stub).
+
+    Handles basic AutoGen chat patterns:
+    - Task extracted from message content or initiate_chat args.
+    - LLM metadata extracted from response dicts.
+    - Tool metadata from function call results.
+
+    Note: This is a minimal stub. Full support for GroupChat, nested chats,
+    and custom speaker selection will be added in a future release.
+    """
+
+    def extract_task(self, args: tuple[Any, ...], kwargs: dict[str, Any]) -> str:
+        """Extract task from AutoGen message or initiate_chat call."""
+        message = kwargs.get("message", "")
+        if message:
+            return str(message)
+        if args:
+            first = args[0]
+            if isinstance(first, dict):
+                return str(first.get("content", first.get("message", first)))
+            return str(first)
+        return ""
+
+    def extract_llm_metadata(self, result: Any) -> dict[str, Any]:
+        """Extract LLM metadata from AutoGen response."""
+        meta: dict[str, Any] = {}
+        if isinstance(result, dict):
+            meta["model"] = result.get("model", "")
+            usage = result.get("usage", {})
+            if isinstance(usage, dict):
+                meta["input_tokens"] = usage.get("prompt_tokens", 0)
+                meta["output_tokens"] = usage.get("completion_tokens", 0)
+        return meta
+
+    def extract_tool_metadata(
+        self, args: tuple[Any, ...], kwargs: dict[str, Any], result: Any
+    ) -> dict[str, Any]:
+        """Extract tool metadata from AutoGen function calls."""
+        meta: dict[str, Any] = {"args": args, "kwargs": kwargs}
+        if isinstance(result, dict):
+            meta["result"] = result.get("content", result)
+        else:
+            meta["result"] = result
+        return meta

specops_ai/adapters/crewai.py

@@ -0,0 +1,80 @@
+"""CrewAI adapter for SpecOps tracing.
+
+Extracts metadata from CrewAI's Crew, Agent, Task, and Process patterns.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from specops_ai.adapters import BaseAdapter
+
+
+class CrewAIAdapter(BaseAdapter):
+    """Adapter for CrewAI framework.
+
+    Handles CrewAI conventions:
+    - Task extracted from CrewAI Task objects or description strings.
+    - LLM metadata extracted from CrewAI's LLM response patterns.
+    - Tool metadata extracted from CrewAI tool execution results.
+    """
+
+    def extract_task(self, args: tuple[Any, ...], kwargs: dict[str, Any]) -> str:
+        """Extract task from CrewAI Task object or kickoff inputs.
+
+        CrewAI patterns:
+        - crew.kickoff(inputs={"topic": "..."})
+        - Task(description="...")
+        - Plain string as first arg
+        """
+        # Check kwargs for CrewAI kickoff inputs
+        inputs = kwargs.get("inputs", {})
+        if isinstance(inputs, dict) and inputs:
+            return str(next(iter(inputs.values())))
+
+        if not args:
+            return str(kwargs.get("task", kwargs.get("description", "")))
+
+        first = args[0]
+        # CrewAI Task object
+        if hasattr(first, "description"):
+            return str(first.description)
+        # Dict with task info
+        if isinstance(first, dict):
+            return str(first.get("description", first.get("task", first)))
+        return str(first)
+
+    def extract_llm_metadata(self, result: Any) -> dict[str, Any]:
+        """Extract LLM metadata from CrewAI results.
+
+        Supports CrewAI's output objects and plain dicts.
+        """
+        meta: dict[str, Any] = {}
+        # CrewAI TaskOutput / CrewOutput with token_usage
+        if hasattr(result, "token_usage"):
+            usage = result.token_usage
+            if isinstance(usage, dict):
+                meta["input_tokens"] = usage.get("prompt_tokens", 0)
+                meta["output_tokens"] = usage.get("completion_tokens", 0)
+                meta["model"] = usage.get("model", "")
+        # Dict fallback
+        if isinstance(result, dict):
+            meta.setdefault("model", result.get("model", ""))
+            usage = result.get("token_usage", result.get("usage", {}))
+            if isinstance(usage, dict):
+                meta.setdefault("input_tokens", usage.get("prompt_tokens", 0))
+                meta.setdefault("output_tokens", usage.get("completion_tokens", 0))
+        return meta
+
+    def extract_tool_metadata(
+        self, args: tuple[Any, ...], kwargs: dict[str, Any], result: Any
+    ) -> dict[str, Any]:
+        """Extract tool metadata from CrewAI tool executions."""
+        meta: dict[str, Any] = {"args": args, "kwargs": kwargs}
+        if hasattr(result, "output"):
+            meta["result"] = result.output
+        elif isinstance(result, dict):
+            meta["result"] = result.get("output", result.get("result", result))
+        else:
+            meta["result"] = result
+        return meta

specops_ai/adapters/langgraph.py

@@ -0,0 +1,88 @@
+"""LangGraph adapter for SpecOps tracing.
+
+Extracts metadata from LangGraph's StateGraph/Pregel execution patterns.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from specops_ai.adapters import BaseAdapter
+
+
+class LangGraphAdapter(BaseAdapter):
+    """Adapter for LangGraph (StateGraph, Pregel, MessageGraph).
+
+    Handles LangGraph conventions:
+    - Task extracted from state dict's "input", "messages", or "task" key.
+    - LLM metadata extracted from AIMessage-like objects or dicts.
+    - Tool metadata extracted from ToolMessage-like objects or dicts.
+    """
+
+    def extract_task(self, args: tuple[Any, ...], kwargs: dict[str, Any]) -> str:
+        """Extract task from LangGraph state input.
+
+        LangGraph invocations typically pass a state dict as the first arg
+        with keys like 'input', 'messages', or 'task'.
+        """
+        state = args[0] if args else kwargs.get("state", kwargs.get("input", {}))
+        if isinstance(state, dict):
+            for key in ("input", "task", "question"):
+                if key in state:
+                    return str(state[key])
+            # Check messages list — use last HumanMessage content
+            messages = state.get("messages", [])
+            if messages:
+                last = messages[-1] if isinstance(messages, list) else messages
+                if hasattr(last, "content"):
+                    return str(last.content)
+                if isinstance(last, dict):
+                    return str(last.get("content", ""))
+        if isinstance(state, str):
+            return state
+        return str(state)[:256] if state else ""
+
+    def extract_llm_metadata(self, result: Any) -> dict[str, Any]:
+        """Extract LLM metadata from LangGraph results.
+
+        Supports AIMessage objects (with usage_metadata) and plain dicts.
+        """
+        meta: dict[str, Any] = {}
+        # AIMessage with usage_metadata (langchain-core pattern)
+        if hasattr(result, "usage_metadata"):
+            usage = result.usage_metadata
+            if isinstance(usage, dict):
+                meta["input_tokens"] = usage.get("input_tokens", 0)
+                meta["output_tokens"] = usage.get("output_tokens", 0)
+            elif hasattr(usage, "input_tokens"):
+                meta["input_tokens"] = usage.input_tokens
+                meta["output_tokens"] = usage.output_tokens
+        if hasattr(result, "response_metadata"):
+            rm = result.response_metadata
+            if isinstance(rm, dict):
+                meta.setdefault("model", rm.get("model_name", rm.get("model", "")))
+        # Dict fallback
+        if isinstance(result, dict):
+            if "model" in result:
+                meta["model"] = result["model"]
+            usage = result.get("usage_metadata", result.get("usage", {}))
+            if isinstance(usage, dict):
+                meta.setdefault("input_tokens", usage.get("input_tokens", 0))
+                meta.setdefault("output_tokens", usage.get("output_tokens", 0))
+        return meta
+
+    def extract_tool_metadata(
+        self, args: tuple[Any, ...], kwargs: dict[str, Any], result: Any
+    ) -> dict[str, Any]:
+        """Extract tool metadata from LangGraph tool invocations.
+
+        Supports ToolMessage objects and plain dicts.
+        """
+        meta: dict[str, Any] = {"args": args, "kwargs": kwargs}
+        if hasattr(result, "content"):
+            meta["result"] = result.content
+        elif isinstance(result, dict):
+            meta["result"] = result.get("content", result.get("output", result))
+        else:
+            meta["result"] = result
+        return meta

specops_ai/config.py

@@ -0,0 +1,76 @@
+"""Auto-configuration for SpecOps tracing."""
+
+from __future__ import annotations
+
+import os
+
+from opentelemetry import trace
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import (
+    ConsoleSpanExporter,
+    SimpleSpanProcessor,
+)
+
+_tracer: trace.Tracer | None = None
+_configured = False
+
+
+def configure(
+    service_name: str | None = None,
+    endpoint: str | None = None,
+    *,
+    enabled: bool = True,
+) -> None:
+    """Configure the SpecOps tracer.
+
+    Falls back to environment variables:
+      - OTEL_SERVICE_NAME (default: "specops")
+      - OTEL_EXPORTER_OTLP_ENDPOINT (default: None → console exporter)
+      - SPECOPS_ENABLED (default: "true")
+    """
+    global _tracer, _configured  # noqa: PLW0603
+
+    if not enabled or os.environ.get("SPECOPS_ENABLED", "true").lower() == "false":
+        _tracer = trace.NoOpTracer()
+        _configured = True
+        return
+
+    svc = service_name or os.environ.get("OTEL_SERVICE_NAME", "specops")
+    resource = Resource.create({"service.name": svc})
+    provider = TracerProvider(resource=resource)
+
+    otlp_endpoint = endpoint or os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT")
+    if otlp_endpoint:
+        try:
+            from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (  # type: ignore[import-not-found]
+                OTLPSpanExporter,
+            )
+
+            exporter = OTLPSpanExporter(endpoint=otlp_endpoint)
+        except ImportError:
+            # Fall back to console if OTLP exporter not installed
+            exporter = ConsoleSpanExporter()
+    else:
+        exporter = ConsoleSpanExporter()
+
+    provider.add_span_processor(SimpleSpanProcessor(exporter))
+    trace.set_tracer_provider(provider)
+    _tracer = provider.get_tracer("specops", "0.1.0")
+    _configured = True
+
+
+def get_tracer() -> trace.Tracer:
+    """Get the configured tracer, initializing with defaults if needed."""
+    global _tracer  # noqa: PLW0603
+    if not _configured:
+        configure()
+    assert _tracer is not None
+    return _tracer
+
+
+def reset() -> None:
+    """Reset configuration (for testing)."""
+    global _tracer, _configured  # noqa: PLW0603
+    _tracer = None
+    _configured = False