nexus-llmops 0.1.0__tar.gz

nexus_llmops-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Env / secrets
+.env
+*.local
+
+# Node / dashboard
+node_modules/
+dashboard/dist/
+.vite/
+
+# ML / data artifacts
+mlruns/
+*.pkl
+*.faiss
+# regenerable embedding cache (keep trained model under data/classifier_model/)
+data/synthetic_embeddings.npy
+data/master_embeddings.npy
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+
+# Experiment caches and cost ledgers are local state, not outputs; results/ is the
+# only tracked output (DECISIONS D48). data/nexusbench/ is benchmark data, tracked.
+data/phase2/
+data/phase4/
+
+# Phase 5 local state and private exports (never commit).
+runs/
+logs/
+*.jsonl
+*.patch
+frozen_patches_export.tgz
+data/phase5/runs/
+data/phase6/runs/
+
+# CI stages exact model revisions locally; inference weights are not source.
+/cross-encoder/
+/sentence-transformers/

nexus_llmops-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sankalp Rajeev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nexus_llmops-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.5
+Name: nexus-llmops
+Version: 0.1.0
+Summary: Python SDK for Nexus: fail-open agent tracing for the Nexus failure-detection and fix-verification service
+Project-URL: Homepage, https://github.com/sankalp-rajeev/Nexus
+Project-URL: Repository, https://github.com/sankalp-rajeev/Nexus
+Project-URL: Bug Tracker, https://github.com/sankalp-rajeev/Nexus/issues
+Author-email: Sankalp Rajeev <srajeev@umich.edu>
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,crewai,langchain,llmops,mlops,observability,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# nexus-llmops
+
+Python SDK for [Nexus](https://github.com/sankalp-rajeev/Nexus): fail-open agent tracing for
+the Nexus failure-detection and fix-verification service.
+
+The SDK records what your agent pipeline does (LLM calls, tool calls, retrieval, memory reads
+and writes, agent steps) as spans and sends them to a Nexus collector. It does no analysis
+itself: failure detection (loops, tool misfires, context bleed, plan drift, hallucination) runs
+in the Nexus service, which you run separately. See the main repository for how.
+
+> **Status: alpha, `0.1.0`.** The API can still change in later `0.x` releases.
+
+- Distribution: `nexus-llmops`. Import name: `nexus_llmops`.
+- Python 3.11+. Dependencies: `httpx` and `pydantic` only (no OpenTelemetry, no protobuf).
+
+## Install
+
+```bash
+pip install nexus-llmops
+```
+
+## Minimal example
+
+```python
+import nexus_llmops as nexus
+
+nexus.init(agent_name="my-pipeline", collector_url="http://localhost:8000")
+
+@nexus.trace(span_type="tool_call")
+def search(query: str) -> str:
+    return "results for " + query
+
+@nexus.trace(span_type="agent_step")
+def run(task: str) -> str:
+    return search(task)
+
+run("find the order")
+nexus.flush()  # before a short-lived script exits
+```
+
+`collector_url` is the collector's address: `http://localhost:8000` for the full stack
+(`docker-compose.yml`), `http://127.0.0.1:18000` for lite mode (`docker-compose.lite.yml`).
+
+Spans nest automatically (trace and parent IDs propagate via `contextvars`). Three ways to
+instrument:
+
+```python
+# 1. decorator (bare or with arguments; sync and async)
+@nexus.trace
+def plan(task: str) -> list[str]: ...
+
+@nexus.trace(span_type="llm_call", model="my-model")
+def call_llm(prompt: str) -> str: ...
+
+# 2. context manager
+with nexus.span("tool_call", input=query, tool="search") as s:
+    s.set_output(search_tool.run(query))
+
+# 3. explicit start/end
+span_id = nexus.start_span("agent_step", step="retrieve")
+nexus.end_span(span_id, output=result)
+```
+
+## Fail-open: your agent is never in Nexus's way
+
+- Nexus only wraps your call to capture timing, output and exceptions. Exceptions from your code
+  always propagate, after being recorded. Nexus's own failures never do.
+- If the collector is down or slow, your program keeps running and finishes normally. Spans that
+  cannot be delivered are dropped and **counted**, not retried forever.
+- With default asynchronous export, capturing a span only enqueues it; it does not wait for HTTP.
+  Each failed export batch is retried **once** on the background thread after a jittered
+  100-300 ms backoff, then dropped and counted. That covers brief transient failures. During a
+  sustained outage batches are dropped (with a throttled warning) and memory stays capped. There
+  is no requeue and no disk persistence, so this is **not a zero-loss guarantee**. A retried batch
+  is delivered at least once, so a collector can see a span twice; span IDs are stable.
+- The queue is bounded two ways, dropping the incoming newest span when exceeded:
+  `max_queue_size` (default 10,000 spans) and `max_queue_bytes` (default 32 MiB; the byte size is
+  an estimate, not exact process memory). Zero or negative limits raise `ValueError`; unbounded
+  queues are not allowed.
+- `nexus.shutdown(timeout=None)` (default `shutdown_timeout_ms`, 5000) drains for at most that
+  long, then discards what is still queued and counts it as `dropped_shutdown`. `flush()` has no
+  deadline; synchronous export and `flush()` can wait for HTTP attempts and never retry.
+
+The client returned by `nexus.init(...)` exposes process-lifetime counters in `client.stats`:
+`produced`, `exported`, `queued`, `pending`, `export_retried` (retry attempts), and the losses
+`dropped_queue_full`, `dropped_bytes_cap`, `export_failed` (spans lost after a failed export and
+its retry) and `dropped_shutdown`, whose sum is `dropped_total`. When idle,
+`produced == exported + dropped_total + queued`. Counters report what happened; they are not
+durable delivery guarantees.
+
+## Trace completion
+
+When the outermost (root) span of a trace ends, the SDK sets `metadata.final = True` on it, so
+the Nexus service can finish and classify the trace right away instead of waiting for an idle
+timeout. Child spans are unchanged. A child span that is delivered after its root has already
+arrived (for example a retried batch) is dropped by the service and counted there.
+
+## Compatibility alias
+
+`nexus_agent` is an alias for `nexus_llmops`: the same module objects under the old name (the
+Nexus research code uses it). New code should import `nexus_llmops`.
+
+## Not included
+
+- No LangChain or other framework callbacks yet (planned, not implemented).
+- No OpenTelemetry exporter here: an application that already uses OpenTelemetry can send OTLP
+  directly to the Nexus collector's `/v1/traces` endpoint; that converter is server-side.
+
+## Links
+
+- [Platform and docs](https://github.com/sankalp-rajeev/Nexus)
+- [Issues](https://github.com/sankalp-rajeev/Nexus/issues)
+- License: MIT (see `LICENSE` in the distribution)

nexus_llmops-0.1.0/README.md

@@ -0,0 +1,113 @@
+# nexus-llmops
+
+Python SDK for [Nexus](https://github.com/sankalp-rajeev/Nexus): fail-open agent tracing for
+the Nexus failure-detection and fix-verification service.
+
+The SDK records what your agent pipeline does (LLM calls, tool calls, retrieval, memory reads
+and writes, agent steps) as spans and sends them to a Nexus collector. It does no analysis
+itself: failure detection (loops, tool misfires, context bleed, plan drift, hallucination) runs
+in the Nexus service, which you run separately. See the main repository for how.
+
+> **Status: alpha, `0.1.0`.** The API can still change in later `0.x` releases.
+
+- Distribution: `nexus-llmops`. Import name: `nexus_llmops`.
+- Python 3.11+. Dependencies: `httpx` and `pydantic` only (no OpenTelemetry, no protobuf).
+
+## Install
+
+```bash
+pip install nexus-llmops
+```
+
+## Minimal example
+
+```python
+import nexus_llmops as nexus
+
+nexus.init(agent_name="my-pipeline", collector_url="http://localhost:8000")
+
+@nexus.trace(span_type="tool_call")
+def search(query: str) -> str:
+    return "results for " + query
+
+@nexus.trace(span_type="agent_step")
+def run(task: str) -> str:
+    return search(task)
+
+run("find the order")
+nexus.flush()  # before a short-lived script exits
+```
+
+`collector_url` is the collector's address: `http://localhost:8000` for the full stack
+(`docker-compose.yml`), `http://127.0.0.1:18000` for lite mode (`docker-compose.lite.yml`).
+
+Spans nest automatically (trace and parent IDs propagate via `contextvars`). Three ways to
+instrument:
+
+```python
+# 1. decorator (bare or with arguments; sync and async)
+@nexus.trace
+def plan(task: str) -> list[str]: ...
+
+@nexus.trace(span_type="llm_call", model="my-model")
+def call_llm(prompt: str) -> str: ...
+
+# 2. context manager
+with nexus.span("tool_call", input=query, tool="search") as s:
+    s.set_output(search_tool.run(query))
+
+# 3. explicit start/end
+span_id = nexus.start_span("agent_step", step="retrieve")
+nexus.end_span(span_id, output=result)
+```
+
+## Fail-open: your agent is never in Nexus's way
+
+- Nexus only wraps your call to capture timing, output and exceptions. Exceptions from your code
+  always propagate, after being recorded. Nexus's own failures never do.
+- If the collector is down or slow, your program keeps running and finishes normally. Spans that
+  cannot be delivered are dropped and **counted**, not retried forever.
+- With default asynchronous export, capturing a span only enqueues it; it does not wait for HTTP.
+  Each failed export batch is retried **once** on the background thread after a jittered
+  100-300 ms backoff, then dropped and counted. That covers brief transient failures. During a
+  sustained outage batches are dropped (with a throttled warning) and memory stays capped. There
+  is no requeue and no disk persistence, so this is **not a zero-loss guarantee**. A retried batch
+  is delivered at least once, so a collector can see a span twice; span IDs are stable.
+- The queue is bounded two ways, dropping the incoming newest span when exceeded:
+  `max_queue_size` (default 10,000 spans) and `max_queue_bytes` (default 32 MiB; the byte size is
+  an estimate, not exact process memory). Zero or negative limits raise `ValueError`; unbounded
+  queues are not allowed.
+- `nexus.shutdown(timeout=None)` (default `shutdown_timeout_ms`, 5000) drains for at most that
+  long, then discards what is still queued and counts it as `dropped_shutdown`. `flush()` has no
+  deadline; synchronous export and `flush()` can wait for HTTP attempts and never retry.
+
+The client returned by `nexus.init(...)` exposes process-lifetime counters in `client.stats`:
+`produced`, `exported`, `queued`, `pending`, `export_retried` (retry attempts), and the losses
+`dropped_queue_full`, `dropped_bytes_cap`, `export_failed` (spans lost after a failed export and
+its retry) and `dropped_shutdown`, whose sum is `dropped_total`. When idle,
+`produced == exported + dropped_total + queued`. Counters report what happened; they are not
+durable delivery guarantees.
+
+## Trace completion
+
+When the outermost (root) span of a trace ends, the SDK sets `metadata.final = True` on it, so
+the Nexus service can finish and classify the trace right away instead of waiting for an idle
+timeout. Child spans are unchanged. A child span that is delivered after its root has already
+arrived (for example a retried batch) is dropped by the service and counted there.
+
+## Compatibility alias
+
+`nexus_agent` is an alias for `nexus_llmops`: the same module objects under the old name (the
+Nexus research code uses it). New code should import `nexus_llmops`.
+
+## Not included
+
+- No LangChain or other framework callbacks yet (planned, not implemented).
+- No OpenTelemetry exporter here: an application that already uses OpenTelemetry can send OTLP
+  directly to the Nexus collector's `/v1/traces` endpoint; that converter is server-side.
+
+## Links
+
+- [Platform and docs](https://github.com/sankalp-rajeev/Nexus)
+- [Issues](https://github.com/sankalp-rajeev/Nexus/issues)
+- License: MIT (see `LICENSE` in the distribution)

nexus_llmops-0.1.0/nexus_agent/__init__.py

@@ -0,0 +1,38 @@
+"""Compatibility alias: ``nexus_agent`` is ``nexus_llmops``.
+
+The distribution ``nexus-llmops`` ships its code as the ``nexus_llmops`` package. The Nexus
+research code predates that name and imports ``nexus_agent``, so this package keeps the old
+name working without a second copy of anything:
+
+* ``sys.modules["nexus_agent"]`` becomes the real ``nexus_llmops`` module object;
+* every submodule and subpackage of ``nexus_llmops`` (found by walking the package, not from a
+  hard-coded list) is registered as ``nexus_agent.<name>``, pointing at the same module object.
+
+So ``nexus_agent.models.Span is nexus_llmops.models.Span``, global state (the client set by
+``init()``) is shared, and ``import nexus_agent.models`` as the very first import gives the
+same objects. There are no re-export copies and no deprecation warning in 0.1.x; new code
+should import ``nexus_llmops``.
+"""
+
+from __future__ import annotations
+
+import importlib
+import pkgutil
+import sys
+
+import nexus_llmops as _real
+
+_OLD = __name__  # "nexus_agent"
+_NEW = _real.__name__  # "nexus_llmops"
+
+
+def _alias_submodules() -> None:
+    for info in pkgutil.walk_packages(_real.__path__, prefix=_NEW + "."):
+        module = importlib.import_module(info.name)
+        sys.modules[_OLD + info.name[len(_NEW):]] = module
+
+
+_alias_submodules()
+# Replace this module with the real package. The import system returns whatever is in
+# sys.modules once this file has run, so ``import nexus_agent`` yields ``nexus_llmops``.
+sys.modules[_OLD] = _real

nexus_llmops-0.1.0/nexus_llmops/__init__.py

@@ -0,0 +1,121 @@
+"""nexus_llmops (dist: nexus-llmops) — fail-open agent tracing for the Nexus service.
+
+``nexus_agent`` is a compatibility alias for this package (same module objects).
+
+Quickstart::
+
+    import nexus_llmops as nexus
+    nexus.init(agent_name="my-pipeline")
+
+    @nexus.trace(span_type="llm_call", model="gemini-2.0-flash")
+    def call_llm(prompt: str) -> str:
+        ...
+
+    nexus.flush()  # before process exit in short-lived scripts
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import threading
+from typing import Any
+
+from nexus_llmops import models  # noqa: F401
+from nexus_llmops.config import NexusConfig
+from nexus_llmops.client import NexusClient
+
+__version__ = "0.1.0"
+
+logger = logging.getLogger("nexus_llmops")
+
+_client: NexusClient | None = None
+_lock = threading.Lock()
+
+
+def init(
+    agent_name: str,
+    collector_url: str = "http://localhost:8000",
+    environment: str = "development",
+    async_export: bool = True,
+    export_timeout_ms: int = 200,
+    debug: bool = False,
+    **kwargs: Any,
+) -> NexusClient:
+    """Initialize the global Nexus client. Safe to call once per process."""
+    global _client
+    with _lock:
+        if _client is not None:
+            logger.warning("nexus: already initialized; reusing existing client")
+            return _client
+        config = NexusConfig(
+            agent_name=agent_name,
+            collector_url=collector_url,
+            environment=environment,
+            async_export=async_export,
+            export_timeout_ms=export_timeout_ms,
+            debug=debug,
+            **kwargs,
+        )
+        _client = NexusClient(config)
+        atexit.register(_client.shutdown)
+        return _client
+
+
+def get_client() -> NexusClient | None:
+    """Return the active client, or None if init() was never called."""
+    return _client
+
+
+def is_initialized() -> bool:
+    return _client is not None
+
+
+def shutdown(timeout: float | None = None) -> None:
+    """Drain (for at most ``timeout`` s; default ``shutdown_timeout_ms``) and stop the exporter.
+
+    Spans still queued at the deadline are counted ``dropped_shutdown``. Resets global state.
+    """
+    global _client
+    with _lock:
+        if _client is not None:
+            _client.shutdown(timeout)
+            _client = None
+
+
+def flush() -> None:
+    """Force-export all queued spans (call before process exit in scripts)."""
+    if _client is not None:
+        _client.flush()
+
+
+def start_span(span_type: Any, agent_name: str | None = None, **metadata: Any) -> str | None:
+    if _client is None:
+        return None
+    return _client.start_span(span_type, agent_name=agent_name, **metadata)
+
+
+def end_span(span_id: str | None, output: Any = None, metadata: dict | None = None) -> None:
+    if _client is None or span_id is None:
+        return
+    _client.end_span(span_id, output=output, metadata=metadata)
+
+
+# Imported last to avoid a circular import (decorators import get_client).
+from nexus_llmops.decorators import span, trace  # noqa: E402
+
+__all__ = [
+    "__version__",
+    "models",
+    "NexusConfig",
+    "NexusClient",
+    "init",
+    "get_client",
+    "is_initialized",
+    "shutdown",
+    "flush",
+    "trace",
+    "span",
+    "start_span",
+    "end_span",
+]