necto-sdk 0.1.0__py3-none-any.whl

necto_sdk/__init__.py

@@ -0,0 +1,35 @@
+"""necto-sdk — instrument multi-agent AI apps for necto.
+
+Quick start:
+
+    from necto_sdk import Necto
+
+    necto = Necto(endpoint="http://127.0.0.1:8000")
+
+    with necto.run(name="demo") as run:
+        run.handoff("router", "researcher", reason="needs sources")
+
+Events are buffered and shipped in the background. The SDK never raises into
+your application: if the necto server is down, events are dropped and logged.
+"""
+
+from ._version import __version__
+from .events import agent, event, external, model, ref, state, tool
+from .tracer import Necto, Run
+from .transport import HttpTransport, NullTransport, RecordingTransport
+
+__all__ = [
+    "Necto",
+    "Run",
+    "HttpTransport",
+    "NullTransport",
+    "RecordingTransport",
+    "agent",
+    "event",
+    "external",
+    "model",
+    "ref",
+    "state",
+    "tool",
+    "__version__",
+]

necto_sdk/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the SDK version (read by hatch at build time)."""
+
+__version__ = "0.1.0"

necto_sdk/adapters/__init__.py

@@ -0,0 +1,20 @@
+"""Framework integrations.
+
+Each adapter is import-safe without its framework installed: frameworks are only
+touched through duck-typed callbacks, never imported at module load.
+"""
+
+from .langgraph import NectoCallbackHandler, attach
+from .openai_agents import NectoProcessor
+from .openai_agents import instrument as instrument_openai_agents
+from .otel import NectoSpanProcessor
+from .otel import instrument as instrument_otel
+
+__all__ = [
+    "NectoCallbackHandler",
+    "NectoProcessor",
+    "NectoSpanProcessor",
+    "attach",
+    "instrument_openai_agents",
+    "instrument_otel",
+]

necto_sdk/adapters/langgraph.py

@@ -0,0 +1,381 @@
+"""LangGraph / LangChain integration.
+
+LangGraph uses the LangChain callback system, so one handler covers both.
+
+Usage:
+
+    from necto_sdk import Necto
+    from necto_sdk.adapters.langgraph import NectoCallbackHandler
+
+    necto = Necto(endpoint="http://127.0.0.1:8000", framework="langgraph")
+    handler = NectoCallbackHandler(necto)
+
+    result = graph.invoke(inputs, config={"callbacks": [handler]})
+
+Mapping:
+
+| LangChain callback        | necto event                |
+|---------------------------|----------------------------|
+| root `on_chain_start`     | creates the run            |
+| `on_chain_start` (node)   | `agent_start`              |
+| node → node transition    | `handoff`                  |
+| `on_chat_model_start/end` | `llm_call` (tokens, ms)    |
+| `on_tool_start/end`       | `tool_call` / `tool_result` |
+| `*_error`                 | `error`                    |
+| root `on_chain_end`       | finishes the run           |
+
+Handoffs are inferred from node-to-node transitions: LangGraph executes nodes in
+sequence, so a change of node is a change of control. This is a heuristic; nested
+subgraphs may produce extra transitions.
+
+This module does not import langchain or langgraph — it works with plain objects
+that expose the same callback signatures.
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+import time
+from typing import Any
+
+from ..tracer import Necto, Run
+
+logger = logging.getLogger(__name__)
+
+
+def _guard(method):
+    """Callbacks must never raise into the framework."""
+
+    @functools.wraps(method)
+    def wrapper(self, *args: Any, **kwargs: Any) -> Any:
+        try:
+            return method(self, *args, **kwargs)
+        except Exception:  # noqa: BLE001 - never break the user's graph
+            logger.warning("necto: langgraph adapter failed in %s", method.__name__, exc_info=True)
+            return None
+
+    return wrapper
+
+
+def _node_name(
+    metadata: dict[str, Any] | None, serialized: Any, kwargs: dict[str, Any]
+) -> str | None:
+    """Best-effort name of the graph node a callback belongs to."""
+    if isinstance(metadata, dict):
+        node = metadata.get("langgraph_node")
+        if node:
+            return str(node)
+    name = kwargs.get("name")
+    if name:
+        return str(name)
+    if isinstance(serialized, dict):
+        for key in ("name", "id"):
+            if serialized.get(key):
+                return str(serialized[key])
+    return None
+
+
+def _model_name(serialized: Any, kwargs: dict[str, Any]) -> tuple[str, str]:
+    """Return (provider, model) from a serialized runnable, best effort."""
+    provider = "unknown"
+    model = "unknown"
+    if isinstance(serialized, dict):
+        for key in ("model_name", "model"):
+            value = serialized.get(key)
+            if value:
+                model = str(value)
+                break
+        else:
+            nested = serialized.get("kwargs")
+            if isinstance(nested, dict):
+                for key in ("model_name", "model"):
+                    if nested.get(key):
+                        model = str(nested[key])
+                        break
+        model_class = str(serialized.get("name") or "")
+        lowered = model_class.lower()
+    else:
+        lowered = ""
+
+    invocations = kwargs.get("invocation_params")
+    if isinstance(invocations, dict):
+        for key in ("model_name", "model"):
+            if invocations.get(key):
+                model = str(invocations[key])
+                break
+
+    if "anthropic" in lowered or "claude" in model.lower():
+        provider = "anthropic"
+    elif "openai" in lowered or "gpt" in model.lower() or model.startswith("o1"):
+        provider = "openai"
+    return provider, model
+
+
+def _token_counts(response: Any) -> tuple[int | None, int | None]:
+    """Extract (prompt_tokens, completion_tokens) from an LLMResult-like object."""
+    usage: dict[str, Any] = {}
+    llm_output = getattr(response, "llm_output", None)
+    if isinstance(llm_output, dict):
+        usage = llm_output.get("token_usage") or llm_output.get("usage") or {}
+    if isinstance(usage, dict) and (usage.get("prompt_tokens") or usage.get("completion_tokens")):
+        return usage.get("prompt_tokens"), usage.get("completion_tokens")
+
+    # newer chat models expose usage_metadata on the message
+    try:
+        message = response.generations[0][0].message
+        meta = getattr(message, "usage_metadata", None)
+        if isinstance(meta, dict):
+            return meta.get("input_tokens"), meta.get("output_tokens")
+    except Exception:  # noqa: BLE001 - shape differs across versions
+        pass
+    return None, None
+
+
+class NectoCallbackHandler:
+    """LangChain/LangGraph callback handler that emits necto events."""
+
+    # LangChain's CallbackManager reads these attributes on every handler; without them a
+    # single callback error turns into AttributeError inside the framework's error path.
+    ignore_llm = False
+    ignore_chain = False
+    ignore_agent = False
+    ignore_retriever = False
+    ignore_chat_model = False
+    raise_error = False
+    run_inline = False
+
+    @property
+    def always_verbose(self) -> bool:
+        return True
+
+    def __init__(
+        self,
+        necto: Necto,
+        *,
+        name: str | None = None,
+        meta: dict[str, Any] | None = None,
+    ) -> None:
+        self.necto = necto
+        self.name = name
+        self.meta = dict(meta or {})
+        self._run: Run | None = None
+        self.last_run_id: str | None = None
+        self._root_id: Any = None
+        self._last_node: str | None = None
+        self._chains: dict[Any, str | None] = {}
+        self._llm_start: dict[Any, tuple[float, str]] = {}
+        self._tool_start: dict[Any, tuple[str, float]] = {}
+
+    # -- helpers -----------------------------------------------------------
+    @property
+    def run(self) -> Run | None:
+        return self._run
+
+    def _ensure_run(self, name: str | None) -> Run:
+        if self._run is None:
+            self._run = self.necto.start_run(name or self.name, self.meta)
+            self.last_run_id = self._run.run_id
+        return self._run
+
+    def _node_for(self, run_id: Any) -> str | None:
+        node = self._chains.get(run_id)
+        return node or self._last_node
+
+    def close(self) -> None:
+        """Finish an in-flight run (safe to call twice)."""
+        if self._run is not None:
+            self._run.finish()
+            self._run = None
+
+    # -- chains ------------------------------------------------------------
+    @_guard
+    def on_chain_start(
+        self,
+        serialized: Any,
+        inputs: Any,
+        *,
+        run_id: Any = None,
+        parent_run_id: Any = None,
+        tags: Any = None,
+        metadata: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        node = _node_name(metadata, serialized, kwargs)
+
+        if parent_run_id is None:
+            # top-level chain: the graph itself starts the necto run
+            self._root_id = run_id
+            self._chains[run_id] = None
+            self._ensure_run(node or self.name)
+            return
+
+        run = self._ensure_run(node or self.name)
+        self._chains[run_id] = node
+
+        is_node = bool(metadata and metadata.get("langgraph_node")) or (
+            parent_run_id == self._root_id
+        )
+        if not is_node or not node:
+            return
+
+        if self._last_node is not None and self._last_node != node:
+            run.handoff(self._last_node, node, reason="langgraph_edge")
+        self._last_node = node
+        run.agent_start(node, name=node)
+
+    @_guard
+    def on_chain_end(
+        self,
+        outputs: Any,
+        *,
+        run_id: Any = None,
+        parent_run_id: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        node = self._chains.get(run_id)
+        if node and self._run is not None:
+            self._run.agent_finish(node)
+        if parent_run_id is None and run_id == self._root_id:
+            self.close()
+
+    @_guard
+    def on_chain_error(
+        self,
+        error: BaseException | None,
+        *,
+        run_id: Any = None,
+        parent_run_id: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        if self._run is not None:
+            node = (
+                self._node_for(run_id) if self._chains.get(run_id) is None else self._chains[run_id]
+            )
+            self._run.error(node or "unknown", str(error or "chain error"))
+
+    # -- models ------------------------------------------------------------
+    @_guard
+    def on_llm_start(
+        self,
+        serialized: Any,
+        prompts: Any,
+        *,
+        run_id: Any = None,
+        parent_run_id: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        provider, model = _model_name(serialized, kwargs)
+        self._llm_start[run_id] = (time.monotonic(), f"{provider}:{model}")
+
+    @_guard
+    def on_chat_model_start(
+        self,
+        serialized: Any,
+        messages: Any,
+        *,
+        run_id: Any = None,
+        parent_run_id: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        self.on_llm_start(
+            serialized, messages, run_id=run_id, parent_run_id=parent_run_id, **kwargs
+        )
+
+    @_guard
+    def on_llm_end(
+        self,
+        response: Any,
+        *,
+        run_id: Any = None,
+        parent_run_id: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        if self._run is None:
+            return
+        started = self._llm_start.pop(run_id, None)
+        latency_ms = int((time.monotonic() - started[0]) * 1000) if started else None
+        provider, model = (
+            (started[1].split(":", 1) + ["unknown"])[:2] if started else ("unknown", "unknown")
+        )
+        input_tokens, output_tokens = _token_counts(response)
+        node = self._node_for(parent_run_id) or self._last_node or "unknown"
+        self._run.llm_call(
+            node,
+            provider,
+            model,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            latency_ms=latency_ms,
+        )
+
+    @_guard
+    def on_llm_error(
+        self,
+        error: BaseException | None,
+        *,
+        run_id: Any = None,
+        parent_run_id: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        if self._run is not None:
+            self._run.error(self._node_for(parent_run_id) or "unknown", str(error or "llm error"))
+
+    # -- tools -------------------------------------------------------------
+    @_guard
+    def on_tool_start(
+        self,
+        serialized: Any,
+        input_str: Any,
+        *,
+        run_id: Any = None,
+        parent_run_id: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        name = _node_name(None, serialized, kwargs) or "tool"
+        self._tool_start[run_id] = (name, time.monotonic())
+        if self._run is not None:
+            node = self._node_for(parent_run_id) or self._last_node or "unknown"
+            self._run.tool_call(node, name, name=name)
+
+    @_guard
+    def on_tool_end(
+        self,
+        output: Any,
+        *,
+        run_id: Any = None,
+        parent_run_id: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        if self._run is None:
+            return
+        started = self._tool_start.pop(run_id, None)
+        name = started[0] if started else "tool"
+        latency_ms = int((time.monotonic() - started[1]) * 1000) if started else None
+        node = self._node_for(parent_run_id) or self._last_node or "unknown"
+        self._run.tool_result(
+            name, node, ok=True, latency_ms=latency_ms, output_snippet=str(output)
+        )
+
+    @_guard
+    def on_tool_error(
+        self,
+        error: BaseException | None,
+        *,
+        run_id: Any = None,
+        parent_run_id: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        started = self._tool_start.pop(run_id, None)
+        name = started[0] if started else "tool"
+        if self._run is not None:
+            node = self._node_for(parent_run_id) or self._last_node or "unknown"
+            self._run.tool_result(name, node, ok=False)
+            self._run.error(name, str(error or "tool error"))
+
+
+def attach(handler: NectoCallbackHandler, config: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Return a LangChain/LangGraph `config` dict with the handler attached."""
+    merged = dict(config or {})
+    merged["callbacks"] = list(merged.get("callbacks") or []) + [handler]
+    return merged

necto_sdk/adapters/openai_agents.py

@@ -0,0 +1,222 @@
+"""OpenAI Agents SDK integration.
+
+The OpenAI Agents SDK ships its own tracing layer: a `TracingProcessor` receives
+trace and span lifecycle events. Registering one is the supported way to observe
+runs, so this adapter implements that interface.
+
+Usage (two lines):
+
+    from necto_sdk import Necto
+    from necto_sdk.adapters.openai_agents import instrument
+
+    necto = Necto(endpoint="http://127.0.0.1:8000", framework="openai-agents")
+    instrument(necto)
+
+    result = await Runner.run(agent, "hello")
+
+Mapping:
+
+| span type        | necto event                        |
+|------------------|------------------------------------|
+| trace start/end  | create / finish the run            |
+| `agent`          | `agent_start` / `agent_finish`      |
+| `handoff`        | `handoff`                          |
+| `generation`     | `llm_call` (model, tokens, latency) |
+| `function`       | `tool_call` / `tool_result`         |
+
+This module never imports `agents` at module load — the processor is duck-typed,
+so importing it without the SDK installed is safe. Only `instrument()` requires
+the SDK, and it raises a clear ImportError if it is missing.
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+from datetime import datetime
+from typing import Any
+
+from ..tracer import Necto, Run
+
+logger = logging.getLogger(__name__)
+
+
+def _guard(method):
+    """Processors must never raise into the agents runtime."""
+
+    @functools.wraps(method)
+    def wrapper(self, *args: Any, **kwargs: Any) -> Any:
+        try:
+            return method(self, *args, **kwargs)
+        except Exception:  # noqa: BLE001 - never break the user's agent run
+            logger.warning(
+                "necto: openai-agents adapter failed in %s", method.__name__, exc_info=True
+            )
+            return None
+
+    return wrapper
+
+
+def _attr(obj: Any, *names: str, default: Any = None) -> Any:
+    for name in names:
+        value = getattr(obj, name, None)
+        if value is not None:
+            return value
+    return default
+
+
+def _latency_ms(start: Any, end: Any) -> int | None:
+    if isinstance(start, datetime) and isinstance(end, datetime):
+        return int((end - start).total_seconds() * 1000)
+    return None
+
+
+def _tokens(usage: Any) -> tuple[int | None, int | None]:
+    if not isinstance(usage, dict):
+        return None, None
+    return (
+        usage.get("input_tokens") or usage.get("prompt_tokens"),
+        usage.get("output_tokens") or usage.get("completion_tokens"),
+    )
+
+
+def _provider(model: str | None) -> str:
+    lowered = (model or "").lower()
+    if "claude" in lowered or "anthropic" in lowered:
+        return "anthropic"
+    if "gemini" in lowered:
+        return "google"
+    return "openai"
+
+
+class NectoProcessor:
+    """A `TracingProcessor` that forwards OpenAI Agents activity to necto."""
+
+    def __init__(
+        self,
+        necto: Necto,
+        *,
+        name: str | None = None,
+        meta: dict[str, Any] | None = None,
+    ) -> None:
+        self.necto = necto
+        self.name = name
+        self.meta = dict(meta or {})
+        self._run: Run | None = None
+        self.last_run_id: str | None = None
+        self._agents: list[str] = []
+        self._tools: dict[Any, str] = {}
+
+    @property
+    def run(self) -> Run | None:
+        return self._run
+
+    def _ensure_run(self, name: str | None = None) -> Run:
+        if self._run is None:
+            self._run = self.necto.start_run(name or self.name, self.meta)
+            self.last_run_id = self._run.run_id
+        return self._run
+
+    def _current_agent(self) -> str:
+        return self._agents[-1] if self._agents else "unknown"
+
+    @staticmethod
+    def _key(span: Any) -> Any:
+        return _attr(span, "span_id", "id", default=id(span))
+
+    # -- trace lifecycle ---------------------------------------------------
+    @_guard
+    def on_trace_start(self, trace: Any) -> None:
+        name = _attr(trace, "workflow_name", "name") or self.name
+        self._ensure_run(str(name) if name else None)
+
+    @_guard
+    def on_trace_end(self, trace: Any) -> None:
+        if self._run is not None:
+            self._run.finish()
+            self._run = None
+
+    @_guard
+    def shutdown(self) -> None:
+        if self._run is not None:
+            self._run.finish()
+            self._run = None
+
+    @_guard
+    def force_flush(self) -> None:
+        self.necto.flush()
+
+    # -- spans -------------------------------------------------------------
+    @_guard
+    def on_span_start(self, span: Any) -> None:
+        data = getattr(span, "span_data", None)
+        kind = getattr(data, "type", None)
+        run = self._ensure_run()
+
+        if kind == "agent":
+            agent = str(_attr(data, "name", default="agent"))
+            self._agents.append(agent)
+            run.agent_start(agent, name=agent)
+        elif kind == "function":
+            name = str(_attr(data, "name", default="tool"))
+            self._tools[self._key(span)] = name
+            run.tool_call(self._current_agent(), name, name=name)
+
+    @_guard
+    def on_span_end(self, span: Any) -> None:
+        data = getattr(span, "span_data", None)
+        kind = getattr(data, "type", None)
+        run = self._ensure_run()
+        latency = _latency_ms(_attr(span, "started_at"), _attr(span, "ended_at"))
+
+        if kind == "agent":
+            agent = str(_attr(data, "name", default="agent"))
+            run.agent_finish(agent, duration_ms=latency)
+            if self._agents and self._agents[-1] == agent:
+                self._agents.pop()
+        elif kind == "handoff":
+            from_agent = str(_attr(data, "from_agent", default="unknown"))
+            to_agent = str(_attr(data, "to_agent", default="unknown"))
+            run.handoff(from_agent, to_agent, reason="openai_agents_handoff")
+        elif kind == "generation":
+            model = str(_attr(data, "model", default="unknown"))
+            input_tokens, output_tokens = _tokens(_attr(data, "usage"))
+            run.llm_call(
+                self._current_agent(),
+                _provider(model),
+                model,
+                input_tokens=input_tokens,
+                output_tokens=output_tokens,
+                latency_ms=latency,
+            )
+        elif kind == "function":
+            name = self._tools.pop(self._key(span), None)
+            if name is None:
+                name = str(_attr(data, "name", default="tool"))
+            output = _attr(data, "output")
+            run.tool_result(
+                name,
+                self._current_agent(),
+                ok=True,
+                latency_ms=latency,
+                output_snippet=str(output) if output is not None else None,
+            )
+
+
+def instrument(
+    necto: Necto, *, name: str | None = None, meta: dict[str, Any] | None = None
+) -> NectoProcessor:
+    """Register a necto processor with the OpenAI Agents SDK.
+
+    Raises ImportError when `openai-agents` is not installed.
+    """
+    try:
+        from agents.tracing import add_trace_processor  # noqa: PLC0415 - optional dependency
+    except ImportError as exc:  # pragma: no cover - depends on environment
+        raise ImportError(
+            "The openai-agents package is required for this adapter: pip install openai-agents"
+        ) from exc
+
+    processor = NectoProcessor(necto, name=name, meta=meta)
+    add_trace_processor(processor)
+    return processor