nodeloom-sdk 0.1.0__tar.gz

nodeloom_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: nodeloom-sdk
+Version: 0.1.0
+Summary: Python SDK for NodeLoom AI agent monitoring and telemetry
+Author-email: NodeLoom <sdk@nodeloom.io>
+License: MIT
+Project-URL: Homepage, https://nodeloom.io
+Project-URL: Documentation, https://docs.nodeloom.io/sdk/python
+Project-URL: Repository, https://github.com/nodeloom/nodeloom-python-sdk
+Keywords: nodeloom,telemetry,monitoring,ai,agents,observability
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.1.0; extra == "crewai"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+
+# NodeLoom Python SDK
+
+Python SDK for instrumenting AI agents and sending telemetry to [NodeLoom](https://nodeloom.io).
+
+## Features
+
+- Fire-and-forget telemetry that never blocks or crashes your application
+- Automatic batching and retry with exponential backoff
+- Context manager support for traces and spans
+- Built-in integrations for LangChain and CrewAI
+- Thread-safe client (individual traces/spans are single-threaded)
+- Bounded in-memory queue prevents unbounded memory growth
+- Configurable via constructor arguments
+
+## Requirements
+
+- Python 3.9+
+
+## Installation
+
+```bash
+pip install nodeloom-sdk
+```
+
+With LangChain integration:
+
+```bash
+pip install nodeloom-sdk[langchain]
+```
+
+With CrewAI integration:
+
+```bash
+pip install nodeloom-sdk[crewai]
+```
+
+## Quick Start
+
+```python
+from nodeloom import NodeLoom, SpanType
+
+client = NodeLoom(api_key="sdk_your_api_key")
+
+with client.trace("my-agent", input={"query": "What is NodeLoom?"}) as trace:
+    with trace.span("llm-call", type=SpanType.LLM) as span:
+        span.set_input({"messages": [{"role": "user", "content": "What is NodeLoom?"}]})
+        # ... call your LLM ...
+        span.set_output({"text": "NodeLoom is an AI agent operations platform."})
+        span.set_token_usage(prompt=15, completion=20, model="gpt-4o")
+
+client.shutdown()
+```
+
+## Traces and Spans
+
+A **trace** represents a single end-to-end agent execution. A **span** represents a unit of work within a trace (an LLM call, tool invocation, retrieval step, etc.).
+
+### Span Types
+
+| Type | Description |
+|------|-------------|
+| `SpanType.LLM` | Language model call |
+| `SpanType.TOOL` | Tool or function invocation |
+| `SpanType.RETRIEVAL` | Vector search or data retrieval |
+| `SpanType.CHAIN` | Pipeline or chain of steps |
+| `SpanType.AGENT` | Sub-agent invocation |
+| `SpanType.CUSTOM` | User-defined operation |
+
+### Nested Spans
+
+```python
+with client.trace("my-agent") as trace:
+    with trace.span("agent-step", type=SpanType.AGENT) as parent:
+        with trace.span("llm-call", type=SpanType.LLM, parent_span_id=parent.span_id) as child:
+            child.set_output({"response": "..."})
+            child.set_token_usage(prompt=10, completion=20, model="gpt-4o")
+```
+
+### Standalone Events
+
+```python
+client.event("guardrail_triggered", level=EventLevel.WARN, data={"rule": "pii_detected"})
+```
+
+### Error Handling
+
+Traces and spans used as context managers automatically catch exceptions, mark the span/trace as `ERROR`, and re-raise:
+
+```python
+with client.trace("my-agent") as trace:
+    with trace.span("risky-call", type=SpanType.TOOL) as span:
+        raise ValueError("something went wrong")
+        # span is automatically marked as ERROR
+    # trace is automatically marked as ERROR
+```
+
+You can also set errors manually:
+
+```python
+span.set_error("Connection timeout")
+trace.end(status=TraceStatus.ERROR, error="Agent failed")
+```
+
+## LangChain Integration
+
+```python
+from nodeloom import NodeLoom
+from nodeloom.integrations.langchain import NodeLoomCallbackHandler
+
+client = NodeLoom(api_key="sdk_your_api_key")
+handler = NodeLoomCallbackHandler(client)
+
+# Pass the handler to any LangChain chain, agent, or LLM
+result = chain.invoke(input, config={"callbacks": [handler]})
+
+client.shutdown()
+```
+
+The callback handler automatically instruments LLM calls, chain runs, tool invocations, and retriever queries with proper parent-child span relationships.
+
+## CrewAI Integration
+
+### Decorator
+
+```python
+from nodeloom import NodeLoom
+from nodeloom.integrations.crewai import instrument_crew
+
+client = NodeLoom(api_key="sdk_your_api_key")
+
+@instrument_crew(client, agent_name="my-crew", agent_version="1.0.0")
+def run_crew():
+    crew = Crew(agents=[...], tasks=[...])
+    return crew.kickoff()
+
+run_crew()
+client.shutdown()
+```
+
+### Manual Instrumentation
+
+```python
+from nodeloom.integrations.crewai import CrewAIInstrumentation
+
+inst = CrewAIInstrumentation(client)
+with inst.trace_crew("my-crew") as ctx:
+    with ctx.task("research", agent="researcher") as span:
+        result = do_research()
+        span.set_output({"result": result})
+```
+
+## Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `api_key` | *required* | SDK API key (starts with `sdk_`) |
+| `endpoint` | `https://api.nodeloom.io` | NodeLoom API base URL |
+| `environment` | `production` | Deployment environment label |
+| `batch_size` | `100` | Max events per batch |
+| `flush_interval` | `5.0` | Seconds between automatic flushes |
+| `max_retries` | `3` | Retry attempts for failed requests |
+| `queue_max_size` | `10000` | Max queued events before dropping |
+| `timeout` | `10.0` | HTTP request timeout in seconds |
+| `enabled` | `True` | Set to `False` to disable telemetry |
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

nodeloom_sdk-0.1.0/README.md

@@ -0,0 +1,175 @@
+# NodeLoom Python SDK
+
+Python SDK for instrumenting AI agents and sending telemetry to [NodeLoom](https://nodeloom.io).
+
+## Features
+
+- Fire-and-forget telemetry that never blocks or crashes your application
+- Automatic batching and retry with exponential backoff
+- Context manager support for traces and spans
+- Built-in integrations for LangChain and CrewAI
+- Thread-safe client (individual traces/spans are single-threaded)
+- Bounded in-memory queue prevents unbounded memory growth
+- Configurable via constructor arguments
+
+## Requirements
+
+- Python 3.9+
+
+## Installation
+
+```bash
+pip install nodeloom-sdk
+```
+
+With LangChain integration:
+
+```bash
+pip install nodeloom-sdk[langchain]
+```
+
+With CrewAI integration:
+
+```bash
+pip install nodeloom-sdk[crewai]
+```
+
+## Quick Start
+
+```python
+from nodeloom import NodeLoom, SpanType
+
+client = NodeLoom(api_key="sdk_your_api_key")
+
+with client.trace("my-agent", input={"query": "What is NodeLoom?"}) as trace:
+    with trace.span("llm-call", type=SpanType.LLM) as span:
+        span.set_input({"messages": [{"role": "user", "content": "What is NodeLoom?"}]})
+        # ... call your LLM ...
+        span.set_output({"text": "NodeLoom is an AI agent operations platform."})
+        span.set_token_usage(prompt=15, completion=20, model="gpt-4o")
+
+client.shutdown()
+```
+
+## Traces and Spans
+
+A **trace** represents a single end-to-end agent execution. A **span** represents a unit of work within a trace (an LLM call, tool invocation, retrieval step, etc.).
+
+### Span Types
+
+| Type | Description |
+|------|-------------|
+| `SpanType.LLM` | Language model call |
+| `SpanType.TOOL` | Tool or function invocation |
+| `SpanType.RETRIEVAL` | Vector search or data retrieval |
+| `SpanType.CHAIN` | Pipeline or chain of steps |
+| `SpanType.AGENT` | Sub-agent invocation |
+| `SpanType.CUSTOM` | User-defined operation |
+
+### Nested Spans
+
+```python
+with client.trace("my-agent") as trace:
+    with trace.span("agent-step", type=SpanType.AGENT) as parent:
+        with trace.span("llm-call", type=SpanType.LLM, parent_span_id=parent.span_id) as child:
+            child.set_output({"response": "..."})
+            child.set_token_usage(prompt=10, completion=20, model="gpt-4o")
+```
+
+### Standalone Events
+
+```python
+client.event("guardrail_triggered", level=EventLevel.WARN, data={"rule": "pii_detected"})
+```
+
+### Error Handling
+
+Traces and spans used as context managers automatically catch exceptions, mark the span/trace as `ERROR`, and re-raise:
+
+```python
+with client.trace("my-agent") as trace:
+    with trace.span("risky-call", type=SpanType.TOOL) as span:
+        raise ValueError("something went wrong")
+        # span is automatically marked as ERROR
+    # trace is automatically marked as ERROR
+```
+
+You can also set errors manually:
+
+```python
+span.set_error("Connection timeout")
+trace.end(status=TraceStatus.ERROR, error="Agent failed")
+```
+
+## LangChain Integration
+
+```python
+from nodeloom import NodeLoom
+from nodeloom.integrations.langchain import NodeLoomCallbackHandler
+
+client = NodeLoom(api_key="sdk_your_api_key")
+handler = NodeLoomCallbackHandler(client)
+
+# Pass the handler to any LangChain chain, agent, or LLM
+result = chain.invoke(input, config={"callbacks": [handler]})
+
+client.shutdown()
+```
+
+The callback handler automatically instruments LLM calls, chain runs, tool invocations, and retriever queries with proper parent-child span relationships.
+
+## CrewAI Integration
+
+### Decorator
+
+```python
+from nodeloom import NodeLoom
+from nodeloom.integrations.crewai import instrument_crew
+
+client = NodeLoom(api_key="sdk_your_api_key")
+
+@instrument_crew(client, agent_name="my-crew", agent_version="1.0.0")
+def run_crew():
+    crew = Crew(agents=[...], tasks=[...])
+    return crew.kickoff()
+
+run_crew()
+client.shutdown()
+```
+
+### Manual Instrumentation
+
+```python
+from nodeloom.integrations.crewai import CrewAIInstrumentation
+
+inst = CrewAIInstrumentation(client)
+with inst.trace_crew("my-crew") as ctx:
+    with ctx.task("research", agent="researcher") as span:
+        result = do_research()
+        span.set_output({"result": result})
+```
+
+## Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `api_key` | *required* | SDK API key (starts with `sdk_`) |
+| `endpoint` | `https://api.nodeloom.io` | NodeLoom API base URL |
+| `environment` | `production` | Deployment environment label |
+| `batch_size` | `100` | Max events per batch |
+| `flush_interval` | `5.0` | Seconds between automatic flushes |
+| `max_retries` | `3` | Retry attempts for failed requests |
+| `queue_max_size` | `10000` | Max queued events before dropping |
+| `timeout` | `10.0` | HTTP request timeout in seconds |
+| `enabled` | `True` | Set to `False` to disable telemetry |
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

nodeloom_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nodeloom-sdk"
+version = "0.1.0"
+description = "Python SDK for NodeLoom AI agent monitoring and telemetry"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [
+    { name = "NodeLoom", email = "sdk@nodeloom.io" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Monitoring",
+]
+keywords = ["nodeloom", "telemetry", "monitoring", "ai", "agents", "observability"]
+dependencies = [
+    "requests>=2.28.0",
+]
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.1.0"]
+crewai = ["crewai>=0.1.0"]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+]
+
+[project.urls]
+Homepage = "https://nodeloom.io"
+Documentation = "https://docs.nodeloom.io/sdk/python"
+Repository = "https://github.com/nodeloom/nodeloom-python-sdk"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-dir]
+"" = "src"

nodeloom_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nodeloom_sdk-0.1.0/src/nodeloom/__init__.py

@@ -0,0 +1,23 @@
+"""NodeLoom Python SDK for AI agent monitoring and telemetry."""
+
+from nodeloom.client import NodeLoomClient
+from nodeloom.config import SDK_VERSION
+from nodeloom.span import Span
+from nodeloom.trace import Trace
+from nodeloom.types import EventLevel, SpanType, TraceStatus
+
+# Convenience alias
+NodeLoom = NodeLoomClient
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    "NodeLoom",
+    "NodeLoomClient",
+    "Trace",
+    "Span",
+    "SpanType",
+    "TraceStatus",
+    "EventLevel",
+    "__version__",
+]

nodeloom_sdk-0.1.0/src/nodeloom/batch_processor.py

@@ -0,0 +1,102 @@
+"""Background daemon thread that batches and sends telemetry events."""
+
+import logging
+import threading
+from typing import Optional
+
+from nodeloom.config import NodeLoomConfig
+from nodeloom.queue import TelemetryQueue
+from nodeloom.transport import HttpTransport
+
+logger = logging.getLogger("nodeloom.batch_processor")
+
+
+class BatchProcessor:
+    """Consumes events from a TelemetryQueue, batches them, and sends
+    them via HttpTransport.
+
+    Batches are flushed when either of the following conditions is met:
+      - The batch reaches ``config.batch_size`` events.
+      - ``config.flush_interval`` seconds have elapsed since the last flush.
+
+    The processor runs on a daemon thread, so it will not prevent the
+    interpreter from exiting. Call ``shutdown()`` to flush remaining
+    events before exit.
+    """
+
+    def __init__(
+        self,
+        config: NodeLoomConfig,
+        telemetry_queue: TelemetryQueue,
+        transport: HttpTransport,
+    ) -> None:
+        self._config = config
+        self._queue = telemetry_queue
+        self._transport = transport
+        self._shutdown_event = threading.Event()
+        self._flush_event = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+
+    def start(self) -> None:
+        """Start the background processing thread."""
+        if self._thread is not None and self._thread.is_alive():
+            return
+        self._shutdown_event.clear()
+        self._thread = threading.Thread(
+            target=self._run,
+            name="nodeloom-batch-processor",
+            daemon=True,
+        )
+        self._thread.start()
+        logger.debug("BatchProcessor started")
+
+    def _run(self) -> None:
+        """Main loop for the background thread."""
+        while not self._shutdown_event.is_set():
+            # Wait for either the flush interval to elapse or a manual
+            # flush signal, whichever comes first.
+            self._flush_event.wait(timeout=self._config.flush_interval)
+            self._flush_event.clear()
+            self._flush_batch()
+
+        # Final flush on shutdown
+        self._flush_batch()
+        logger.debug("BatchProcessor stopped")
+
+    def _flush_batch(self) -> None:
+        """Drain events from the queue and send them in batches."""
+        while not self._queue.is_empty():
+            events = self._queue.drain(self._config.batch_size)
+            if not events:
+                break
+            try:
+                self._transport.send_batch(events)
+            except Exception:
+                logger.exception("Unexpected error while sending batch")
+
+    def flush(self) -> None:
+        """Request an immediate flush of pending events.
+
+        This signals the background thread to wake up and process
+        whatever is currently in the queue. It does not block until
+        the flush completes.
+        """
+        self._flush_event.set()
+
+    def shutdown(self, timeout: float = 10.0) -> None:
+        """Signal the processor to stop and wait for it to finish.
+
+        Args:
+            timeout: Maximum seconds to wait for the background thread
+                     to complete its final flush.
+        """
+        logger.debug("BatchProcessor shutting down")
+        self._shutdown_event.set()
+        self._flush_event.set()  # Wake the thread if it is sleeping
+        if self._thread is not None and self._thread.is_alive():
+            self._thread.join(timeout=timeout)
+            if self._thread.is_alive():
+                logger.warning(
+                    "BatchProcessor thread did not terminate within %.1f seconds",
+                    timeout,
+                )