continuous-intelligence-layer 0.1.0__py3-none-any.whl

continuous_intelligence_layer/_core/utils.py

@@ -0,0 +1,170 @@
+"""
+utils.py
+--------
+Helpers for reading and displaying traces after a run.
+
+These are convenience functions — the SDK works without them.
+Use them for quick terminal inspection or to load traces into pandas/analysis.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def load_traces(path: str) -> list[dict]:
+    """
+    Load all spans from a JSONL trace file into a list of dicts.
+
+    Parameters
+    ----------
+    path :
+        Path to the .jsonl file written by ExecutionSpanExporter.
+
+    Returns
+    -------
+    list[dict]
+        One dict per span, in the order they were written.
+
+    Example
+    -------
+        records = load_traces("./execution_trace.jsonl")
+        llm_spans = [r for r in records if r["node_type"] == "LLM"]
+        total_tokens = sum(r["tokens"]["total"] or 0 for r in llm_spans)
+    """
+    records: list[dict] = []
+    p = Path(path)
+    if not p.exists():
+        return records
+    with open(p, encoding="utf-8") as fh:
+        for line in fh:
+            line = line.strip()
+            if line:
+                try:
+                    records.append(json.loads(line))
+                except json.JSONDecodeError:
+                    pass  # skip malformed lines
+    return records
+
+
+def print_trace_summary(path: str) -> None:
+    """
+    Print a human-readable summary of all spans in a JSONL trace file.
+
+    Shows the call tree with indentation (root spans vs child spans),
+    node type, operation name, latency, token usage, and errors.
+
+    Parameters
+    ----------
+    path :
+        Path to the .jsonl file written by ExecutionSpanExporter.
+    """
+    records = load_traces(path)
+    if not records:
+        print(f"\n[continuous-intelligence-layer] No spans found in {path}")
+        return
+
+    # Count by type
+    type_counts: dict[str, int] = {}
+    total_tokens = 0
+    total_latency = 0.0
+    errors = 0
+
+    print(f"\n{'━'*70}")
+    print(f"  📊 Execution Trace  ·  {path}")
+    print(f"  Total Spans: {len(records)}")
+    print(f"{'━'*70}")
+
+    # Build a parent lookup for indentation
+    span_ids = {r["span_id"] for r in records}
+
+    for r in records:
+        node_type  = r.get("node_type", "Unknown")
+        operation  = r.get("operation", "?")
+        latency    = r.get("latency_ms", 0.0)
+        status     = r.get("status", "UNSET")
+        error      = r.get("error")
+        tokens     = r.get("tokens", {}) or {}
+        tok_total  = tokens.get("total")
+        model      = r.get("model") or ""
+        tool       = r.get("tool_name") or ""
+        parent_id  = r.get("parent_span_id")
+
+        # Indent child spans
+        indent = "    " if (parent_id and parent_id in span_ids) else ""
+
+        # Status icon
+        if status == "OK":
+            icon = "✅"
+        elif status == "ERROR":
+            icon = "❌"
+        else:
+            icon = "⚪"
+
+        # Extra label
+        extra = ""
+        if model:
+            extra = f"  [{model}]"
+        elif tool:
+            extra = f"  [{tool}]"
+
+        tok_str = f"  tokens={tok_total}" if tok_total is not None else ""
+
+        print(
+            f"  {indent}{icon} [{node_type:<10}]  {operation:<38}"
+            f"{latency:>8.1f} ms{tok_str}{extra}"
+        )
+
+        if error:
+            print(f"  {indent}         ⚠  Error: {str(error)[:80]}")
+
+        # Accumulate stats
+        type_counts[node_type] = type_counts.get(node_type, 0) + 1
+        if tok_total:
+            total_tokens += tok_total
+        total_latency += latency
+        if status == "ERROR":
+            errors += 1
+
+    print(f"{'━'*70}")
+    print(f"  Node types  : {type_counts}")
+    print(f"  Total tokens: {total_tokens}")
+    print(f"  Total latency: {total_latency:.1f} ms")
+    print(f"  Errors      : {errors}")
+    print(f"{'━'*70}\n")
+
+
+def spans_to_dataframe(path: str) -> Any:
+    """
+    Load traces into a pandas DataFrame.
+
+    Requires pandas to be installed.  Returns None if pandas is not available.
+
+    Parameters
+    ----------
+    path : str
+        Path to the JSONL trace file.
+    """
+    try:
+        import pandas as pd   # type: ignore[import]
+    except ImportError:
+        print("[continuous-intelligence-layer] pandas not installed. Run: pip install pandas")
+        return None
+
+    records = load_traces(path)
+    if not records:
+        return pd.DataFrame()
+
+    # Flatten the tokens dict into columns
+    rows = []
+    for r in records:
+        flat = dict(r)
+        tokens = flat.pop("tokens", {}) or {}
+        flat["tokens_prompt"]     = tokens.get("prompt")
+        flat["tokens_completion"] = tokens.get("completion")
+        flat["tokens_total"]      = tokens.get("total")
+        rows.append(flat)
+
+    return pd.DataFrame(rows)

continuous_intelligence_layer/anthropic/__init__.py

@@ -0,0 +1,9 @@
+"""Direct Anthropic SDK integration for continuous_intelligence_layer.
+
+    from continuous_intelligence_layer.anthropic import init
+    init(api_key=...)
+"""
+from .init import init, reset
+from .._core.utils import load_traces, print_trace_summary
+
+__all__ = ["init", "reset", "load_traces", "print_trace_summary"]

continuous_intelligence_layer/anthropic/init.py

@@ -0,0 +1,232 @@
+"""
+init.py
+-------
+The public entry point for direct Anthropic SDK agents.
+
+    from continuous_intelligence_layer.anthropic import init
+    init(api_key=...)
+
+That's all the user needs to write. Everything else is automatic.
+
+How it works (internals)
+------------------------
+1.  We create an ExecutionSpanExporter — our custom JSONL writer.
+2.  We build an OpenTelemetry TracerProvider and attach the exporter via a
+    SimpleSpanProcessor.  SimpleSpanProcessor calls exporter.export() *synchronously*
+    on every span that finishes, so nothing is lost even if the process exits abruptly.
+3.  We set this provider as the GLOBAL OTel provider for the Python process.
+    Any library that uses `opentelemetry.trace.get_tracer(...)` will now use it.
+4.  We call instrument(provider) which activates the OpenInference
+    AnthropicInstrumentor (see instrumentation.py). This patches the
+    `anthropic.resources.messages.Messages`/`AsyncMessages` classes to emit
+    an OTel LLM span (with tool_calls metadata, normalized token counts) for
+    every `messages.create`/`.stream`/`.parse` call — completely
+    automatically, regardless of which file in the caller's codebase
+    instantiates `anthropic.Anthropic()` or issues the call.
+5.  When the user's agent runs, spans flow:
+        anthropic SDK  →  OpenInference patch  →  OTel SDK  →  SimpleSpanProcessor
+        →  ExecutionSpanExporter.export()  →  JSONL file on disk
+"""
+
+from __future__ import annotations
+
+import uuid
+import requests
+
+from opentelemetry import trace
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+
+from .._core.exporter import ExecutionSpanExporter
+from .instrumentation import instrument
+
+# Guard against double-init in the same process
+_INITIALIZED: bool = False
+_PROVIDER: TracerProvider | None = None
+
+
+def init(
+    api_key: str,
+    output_path: str = "./execution_trace.jsonl",
+    service_name: str = "continuous-intelligence-layer",
+    execution_id: str | None = None,
+    session_id: str | None = None,
+    store: str | None = "mongodb",
+    write_jsonl: bool = False,
+    verbose: bool = True,
+    base_url: str = "http://localhost:8080",
+    run_evaluations: bool = True,
+    evaluation_api_key: str = "",
+    evaluation_provider: str = "openai",
+    evaluation_model: str = "gpt-5.6-luna",
+) -> dict:
+    """
+    Initialize the Continuous Intelligence Layer SDK for direct Anthropic SDK agents.
+
+    Call this ONCE, at the very top of your script, before instantiating any
+    `anthropic.Anthropic()` client.  No other changes to your agent code are
+    required.
+
+    Parameters
+    ----------
+    output_path :
+        Path to the JSONL file where spans will be appended, if
+        ``write_jsonl=True``. File is created automatically; parent dirs are
+        created if needed. Each call to init() with a new execution_id
+        appends to the same file, so you can accumulate traces from multiple
+        runs.
+    write_jsonl :
+        If True, also append every span to a local JSONL file at
+        ``output_path``. Defaults to False when ``store="mongodb"`` — MongoDB
+        is the single source of truth by default, and JSONL is only an
+        opt-in local debug/backup mechanism. Automatically forced on when
+        ``store`` is not "mongodb" (otherwise nothing would be persisted).
+    service_name :
+        An arbitrary label written to every span as ``service.name``.
+        Useful when you have multiple agents writing to the same file.
+    execution_id :
+        A short identifier for *this* pipeline run.  Auto-generated (12-char
+        UUID fragment) if not provided.  Stored on every span as
+        ``execution_id``, so you can filter a single run later.
+    session_id :
+        Identifier for the conversational session/thread.
+    store :
+        Optional. If set to "mongodb", also buffers spans and saves them to
+        MongoDB on shutdown.
+    verbose :
+        Print a one-line confirmation when init succeeds.
+    run_evaluations :
+        If True (the default), evaluations and RCA run automatically on the
+        backend right after the trace finishes ingesting — no need to call
+        the ``run-evaluations`` endpoint or click "Run Evaluation" in the UI
+        separately. Pass False to keep today's behavior: evaluations only
+        run when triggered manually.
+
+    Returns
+    -------
+    dict
+        ``{"execution_id": str, "output_path": str}``
+        Keep a reference if you need to correlate spans to a run ID later.
+
+    Notes
+    -----
+    Calling init() a second time in the same process is a no-op — the existing
+    provider is reused.  If you genuinely need a fresh provider (e.g., in
+    tests), call ``reset()`` first.
+    """
+    global _INITIALIZED, _PROVIDER
+
+    if _INITIALIZED:
+        if verbose:
+            print(
+                f"[continuous-intelligence-layer] ⚠  Already initialized — skipping. "
+                f"Call reset() first if you need a fresh provider."
+            )
+        return {"execution_id": execution_id or "unknown", "output_path": output_path}
+
+    execution_id = execution_id or str(uuid.uuid4())[:12]
+    session_id = session_id or str(uuid.uuid4())[:12]
+
+    # ── Step 1: Build the span exporter ─────────────────────────────────────
+    write_jsonl = write_jsonl or store != "mongodb"
+    exporter = ExecutionSpanExporter(
+        output_path=output_path,
+        execution_id=execution_id,
+        session_id=session_id,
+    )
+
+    # ── Step 2: Sync Project & Build TracerProvider ────────────────────────
+    if not api_key:
+        raise ValueError("API Key is not provided. An API Key is required to initialize the SDK.")
+
+    if not evaluation_api_key:
+        raise ValueError(
+            "evaluation_api_key is not provided. An LLM API key (OpenAI, Anthropic, "
+            "or Gemini) is required to initialize the SDK -- it's used to run "
+            "evaluations and RCA on your traces. We never use our own key for your work."
+        )
+
+    try:
+        res = requests.post(
+            f"{base_url}/projects/sync",
+            json={
+                "name": service_name,
+                "execution_id": execution_id,
+                "evaluation_provider": evaluation_provider,
+                "evaluation_model": evaluation_model,
+                "evaluation_api_key": evaluation_api_key,
+            },
+            headers={"x-api-key": api_key}
+        )
+        if res.status_code == 401:
+            raise ValueError("API Key is not valid.")
+        res.raise_for_status()
+        project_id = res.json()["id"]
+    except requests.exceptions.RequestException as e:
+        raise ValueError(f"Failed to verify API key with backend: {e}")
+
+    resource_attrs = {
+        "service.name": service_name,
+        "project.id": project_id,
+        "execution.id": execution_id,
+        "sdk.name":     "continuous-intelligence-layer",
+        "sdk.version":  "0.1.0",
+    }
+    if session_id:
+        resource_attrs["session.id"] = session_id
+
+    resource = Resource.create(resource_attrs)
+    provider = TracerProvider(resource=resource)
+
+    # ── Step 3: Attach SimpleSpanProcessor ────────────────────────────────
+    if write_jsonl:
+        provider.add_span_processor(SimpleSpanProcessor(exporter))
+
+    if store == "mongodb":
+        from .._core.graph_exporter import GraphSpanExporter
+        graph_exporter = GraphSpanExporter(
+            exporter,
+            session_id=session_id,
+            base_url=base_url,
+            api_key=api_key,
+            project_id=project_id,
+            run_evaluations=run_evaluations,
+        )
+        provider.add_span_processor(SimpleSpanProcessor(graph_exporter))
+
+    # ── Step 4: Set as global OTel provider ───────────────────────────────
+    trace.set_tracer_provider(provider)
+    _PROVIDER = provider
+
+    # ── Step 5: Auto-instrument the direct Anthropic SDK ────────────────────
+    instrument(provider)
+
+    _INITIALIZED = True
+
+    if verbose:
+        store_line = f"  Store         : MongoDB (project={service_name})\n" if store == "mongodb" else ""
+        jsonl_line = f"  Output file   : {output_path}\n" if write_jsonl else ""
+        print(
+            f"[continuous-intelligence-layer] ✅ Initialized\n"
+            f"  Execution ID  : {execution_id}\n"
+            f"{store_line}"
+            f"{jsonl_line}"
+            f"  Service name  : {service_name}"
+        )
+
+    return {"execution_id": execution_id, "output_path": output_path}
+
+
+def reset() -> None:
+    """
+    Reset the SDK so init() can be called again.
+
+    Primarily useful in test suites where each test needs a fresh provider.
+    Calling this in production code is rarely needed.
+    """
+    global _INITIALIZED, _PROVIDER
+    from .instrumentation import uninstrument
+    uninstrument()
+    _INITIALIZED = False
+    _PROVIDER = None

continuous_intelligence_layer/anthropic/instrumentation.py

@@ -0,0 +1,91 @@
+"""
+instrumentation.py
+------------------
+Activates OpenInference auto-instrumentation for direct Anthropic SDK agents.
+
+How OpenInference works internally
+------------------------------------
+`openinference-instrumentation-anthropic`'s `AnthropicInstrumentor` patches
+the `anthropic.resources.messages.Messages`/`AsyncMessages` (and
+`beta.messages`) classes directly — `Messages.create`, `.stream`, `.parse`,
+and their async variants — not any particular `anthropic.Anthropic()`
+instance. Because the patch lives on the shared class, it's active for every
+client built anywhere in the process (any file, any module, instantiated
+before or after `init()` — only the actual `.create()`/`.stream()` call needs
+to happen after `instrument()` has run), exactly like the direct OpenAI SDK
+integration.
+
+Key-name mapping (Anthropic → OpenInference)
+---------------------------------------------
+Anthropic's Messages API has different field names than OpenAI's Chat
+Completions API; OpenInference normalizes them onto the same
+semantic-convention keys `_core/exporter.py` already reads — no exporter
+changes were needed to support this framework:
+  usage.input_tokens (+ cache_creation_input_tokens + cache_read_input_tokens)
+                                        → llm.token_count.prompt
+  usage.output_tokens                  → llm.token_count.completion
+  message.model                        → llm.model_name
+  system param + messages list         → llm.input_messages (role="system" synthesized
+                                          as message 0 from the top-level `system` kwarg,
+                                          which Anthropic — unlike OpenAI — passes
+                                          separately from `messages`)
+  response.content blocks              → llm.output_messages
+  tool_use content blocks              → llm.output_messages.*.message.tool_calls.*
+  tools param                          → llm.tools.*.tool.json_schema
+
+Anthropic-specific attribute `llm.system = "anthropic"` (openinference.instrumentation.LLM_SYSTEM)
+is also set on every span; it lands in `metadata` since `_core/exporter.py`
+only pulls out the vocabulary it knows about — this is expected, not a gap.
+"""
+
+from __future__ import annotations
+
+from opentelemetry.sdk.trace import TracerProvider
+
+_instrumentor = None
+
+
+def instrument(provider: TracerProvider) -> None:
+    """
+    Activate direct Anthropic SDK OpenInference auto-instrumentation.
+
+    Parameters
+    ----------
+    provider :
+        The TracerProvider to attach spans to. Must be the same provider that
+        was set as the global OTel provider.
+    """
+    global _instrumentor
+    if _instrumentor is not None:
+        # Already instrumented — avoid double-patching
+        return
+
+    try:
+        from openinference.instrumentation.anthropic import AnthropicInstrumentor
+    except ImportError:
+        print(
+            "[continuous-intelligence-layer] ⚠️  openinference-instrumentation-anthropic not found.\n"
+            "  anthropic spans will NOT be captured automatically.\n"
+            "  Fix: pip install openinference-instrumentation-anthropic"
+        )
+        return
+
+    try:
+        instrumentor = AnthropicInstrumentor()
+        instrumentor.instrument(tracer_provider=provider)
+        _instrumentor = instrumentor
+        print("[continuous-intelligence-layer] 🔌 anthropic auto-instrumentation active.")
+    except Exception as exc:
+        print(f"[continuous-intelligence-layer] ⚠️  Instrumentation of 'anthropic' failed: {exc}")
+
+
+def uninstrument() -> None:
+    """Remove direct Anthropic SDK OpenInference instrumentation."""
+    global _instrumentor
+    if _instrumentor is None:
+        return
+    try:
+        _instrumentor.uninstrument()
+    except Exception:
+        pass
+    _instrumentor = None

continuous_intelligence_layer/crewai/__init__.py

@@ -0,0 +1,9 @@
+"""CrewAI integration for continuous_intelligence_layer.
+
+    from continuous_intelligence_layer.crewai import init
+    init(api_key=...)
+"""
+from .init import init, reset
+from .._core.utils import load_traces, print_trace_summary
+
+__all__ = ["init", "reset", "load_traces", "print_trace_summary"]