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

continuous_intelligence_layer/openai/init.py

@@ -0,0 +1,229 @@
+"""
+init.py
+-------
+The public entry point for direct OpenAI SDK agents.
+
+    from continuous_intelligence_layer.openai import init
+    init()
+
+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
+    OpenAIInstrumentor (see instrumentation.py). This patches the
+    `openai.OpenAI()` client to emit an OTel LLM span (with tool_calls
+    metadata) for every `chat.completions.create` call — completely
+    automatically.
+5.  When the user's agent runs, spans flow:
+        openai 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 OpenAI SDK agents.
+
+    Call this ONCE, at the very top of your script, before instantiating any
+    `openai.OpenAI()` 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 OpenAI 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/openai/instrumentation.py

@@ -0,0 +1,67 @@
+"""
+instrumentation.py
+------------------
+Activates OpenInference auto-instrumentation for direct OpenAI SDK agents.
+
+How OpenInference works internally
+------------------------------------
+The instrumentor patches the `openai.OpenAI()` client at import/instantiation
+time and emits OTel spans using the vendor-neutral semantic-convention
+attribute names (openinference.span.kind, input.value, llm.model_name,
+tool.name, etc. — see `continuous_intelligence_layer/_core/exporter.py`).
+Because every OpenInference instrumentor speaks that shared vocabulary, the
+rest of the SDK (`_core/`, `graph_builder/`, `evaluators/`, `rca_engine/`)
+doesn't need to know which framework produced a given span.
+"""
+
+from __future__ import annotations
+
+from opentelemetry.sdk.trace import TracerProvider
+
+_instrumentor = None
+
+
+def instrument(provider: TracerProvider) -> None:
+    """
+    Activate direct OpenAI 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.openai import OpenAIInstrumentor
+    except ImportError:
+        print(
+            "[continuous-intelligence-layer] ⚠️  openinference-instrumentation-openai not found.\n"
+            "  openai spans will NOT be captured automatically.\n"
+            "  Fix: pip install openinference-instrumentation-openai"
+        )
+        return
+
+    try:
+        instrumentor = OpenAIInstrumentor()
+        instrumentor.instrument(tracer_provider=provider)
+        _instrumentor = instrumentor
+        print("[continuous-intelligence-layer] 🔌 openai auto-instrumentation active.")
+    except Exception as exc:
+        print(f"[continuous-intelligence-layer] ⚠️  Instrumentation of 'openai' failed: {exc}")
+
+
+def uninstrument() -> None:
+    """Remove direct OpenAI SDK OpenInference instrumentation."""
+    global _instrumentor
+    if _instrumentor is None:
+        return
+    try:
+        _instrumentor.uninstrument()
+    except Exception:
+        pass
+    _instrumentor = None