agentgraf 0.1.0__tar.gz

agentgraf-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+
+# Node
+node_modules/
+.output/
+/public/build/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env
+.env
+.env.local

agentgraf-0.1.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: agentgraf
+Version: 0.1.0
+Summary: Zero-infrastructure AI agent tracing for Grafana + Loki
+Project-URL: Homepage, https://github.com/Berg-it/agentgraf
+Project-URL: Documentation, https://github.com/Berg-it/agentgraf#readme
+Project-URL: Repository, https://github.com/Berg-it/agentgraf
+Project-URL: Issues, https://github.com/Berg-it/agentgraf/issues
+Author-email: Mohamed Amine Berguiga <m.a.berguiga@gmail.com>
+License: MIT
+Keywords: ai-agent,grafana,langchain,llm,loki,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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2.0; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# agentgraf — Python Tracer
+
+Zero-infrastructure AI agent tracing for Grafana + Loki.
+
+```bash
+pip install agentgraf              # core only
+pip install agentgraf[langchain]   # with LangChain callback
+```

agentgraf-0.1.0/README.md

@@ -0,0 +1,8 @@
+# agentgraf — Python Tracer
+
+Zero-infrastructure AI agent tracing for Grafana + Loki.
+
+```bash
+pip install agentgraf              # core only
+pip install agentgraf[langchain]   # with LangChain callback
+```

agentgraf-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentgraf"
+version = "0.1.0"
+description = "Zero-infrastructure AI agent tracing for Grafana + Loki"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Mohamed Amine Berguiga", email = "m.a.berguiga@gmail.com" }
+]
+keywords = ["tracing", "llm", "langchain", "grafana", "loki", "observability", "ai-agent"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Monitoring",
+]
+
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+langchain = [
+    "langchain-core>=0.2.0",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "mypy>=1.10",
+    "ruff>=0.4",
+    "respx>=0.21",
+]
+
+[project.urls]
+Homepage = "https://github.com/Berg-it/agentgraf"
+Documentation = "https://github.com/Berg-it/agentgraf#readme"
+Repository = "https://github.com/Berg-it/agentgraf"
+Issues = "https://github.com/Berg-it/agentgraf/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["tracer/src/agentgraf"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "C4", "SIM"]
+ignore = ["E501"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true
+show_error_codes = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tracer/tests"]

agentgraf-0.1.0/src/agentgraf/__init__.py

@@ -0,0 +1,40 @@
+"""AgentGraf — Zero-infrastructure AI agent tracing for Grafana + Loki.
+
+Usage::
+
+    from agentgraf import LokiClient, BatchSpanProcessor, TraceSpan
+
+    client = LokiClient(loki_url="http://loki:3100/loki/api/v1/push")
+    processor = BatchSpanProcessor(exporter=client.send_spans_sync)
+    processor.start()
+
+    # ... add spans manually or use AgentGrafTracer (LangChain) ...
+
+    processor.shutdown()
+
+Optional LangChain integration (``pip install agentgraf[langchain]``)::
+
+    from agentgraf import AgentGrafTracer
+    tracer = AgentGrafTracer(processor=processor)
+    graph.astream(state, config={"callbacks": [tracer]})
+"""
+
+from .models import SpanKind, SpanStatus, TraceSpan
+from .client import LokiClient
+from .processor import BatchSpanProcessor
+
+__all__ = [
+    "TraceSpan",
+    "SpanKind",
+    "SpanStatus",
+    "LokiClient",
+    "BatchSpanProcessor",
+]
+
+# Lazy import for LangChain tracer — only available if langchain-core is installed.
+try:
+    from .tracer import AgentGrafTracer  # noqa: F401
+
+    __all__.append("AgentGrafTracer")
+except ImportError:
+    pass

agentgraf-0.1.0/src/agentgraf/client.py

@@ -0,0 +1,208 @@
+"""Loki-direct HTTP client — dual sync/async, auto-detects execution context.
+
+Push spans directly to Loki's push API. No Gateway required in v0.1.0.
+
+Loki API reference: POST /loki/api/v1/push
+Payload: {"streams": [{"stream": {...labels...}, "values": [[ts_ns, line, metadata]]}]}
+
+Timestamps must be **string nanosecond-epoch** or Loki returns 400.
+Structured metadata (3rd tuple element) is a Loki >=3.0 feature — older Loki
+versions silently ignore it, so the fallback is the JSON body parsed via ``| json``
+in LogQL.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from .models import TraceSpan
+
+logger = logging.getLogger("agentgraf.client")
+
+# Loki labels kept intentionally low-cardinality — never put run_id/trace_id here.
+_STATIC_LABELS = {"job": "agentgraf"}
+
+
+class LokiClient:
+    """Push spans to Loki HTTP API. Dual sync/async, auto-detects context.
+
+    Args:
+        loki_url: Full Loki push endpoint (e.g. ``http://loki:3100/loki/api/v1/push``).
+        max_retries: Number of retry attempts on transient failures (5xx, timeouts).
+        retry_delay: Base delay in seconds before first retry (default 1.0).
+        timeout: HTTP request timeout in seconds (default 10).
+    """
+
+    def __init__(
+        self,
+        loki_url: str,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+        timeout: float = 10.0,
+    ):
+        self._url = loki_url.rstrip("/")
+        self._max_retries = max_retries
+        self._retry_delay = retry_delay
+        self._timeout = timeout
+        self._sync_client: Optional[httpx.Client] = None
+        self._async_client: Optional[httpx.AsyncClient] = None
+
+    # ------------------------------------------------------------------
+    #  Public API — sync
+    # ------------------------------------------------------------------
+    def send_spans_sync(self, spans: List[TraceSpan]) -> bool:
+        """Push a batch of spans to Loki from a synchronous context.
+
+        Retries on 5xx and network errors. Does NOT retry 4xx
+        (client errors will not resolve on their own).
+        """
+        if self._sync_client is None:
+            self._sync_client = httpx.Client(timeout=self._timeout)
+        payload = _build_loki_payload(spans)
+        for attempt in range(1, self._max_retries + 1):
+            try:
+                resp = self._sync_client.post(
+                    self._url,
+                    json=payload,
+                    headers={"Content-Type": "application/json"},
+                )
+                if resp.status_code < 300:
+                    return True
+
+                if 400 <= resp.status_code < 500:
+                    # Client error — not retryable
+                    logger.warning(
+                        "Loki push returned %d (client error, not retrying): %s",
+                        resp.status_code,
+                        resp.text[:200],
+                    )
+                    return False
+
+                # Server error (5xx) — retryable
+                logger.warning(
+                    "Loki push returned %d (attempt %d/%d): %s",
+                    resp.status_code,
+                    attempt,
+                    self._max_retries,
+                    resp.text[:200],
+                )
+            except httpx.HTTPError as exc:
+                logger.warning(
+                    "Loki push failed (attempt %d/%d): %s",
+                    attempt,
+                    self._max_retries,
+                    exc,
+                )
+            if attempt < self._max_retries:
+                time.sleep(self._retry_delay * (2 ** (attempt - 1)))
+        logger.error(
+            "Failed to push %d spans to Loki after %d attempts", len(spans), self._max_retries
+        )
+        return False
+
+    # ------------------------------------------------------------------
+    #  Public API — async
+    # ------------------------------------------------------------------
+    async def send_spans_async(self, spans: List[TraceSpan]) -> bool:
+        """Push a batch of spans to Loki from an async context.
+
+        Retries on 5xx and network errors. Does NOT retry 4xx.
+        """
+        if self._async_client is None:
+            self._async_client = httpx.AsyncClient(timeout=self._timeout)
+        payload = _build_loki_payload(spans)
+        for attempt in range(1, self._max_retries + 1):
+            try:
+                resp = await self._async_client.post(
+                    self._url,
+                    json=payload,
+                    headers={"Content-Type": "application/json"},
+                )
+                if resp.status_code < 300:
+                    return True
+
+                if 400 <= resp.status_code < 500:
+                    logger.warning(
+                        "Loki push returned %d (client error, not retrying): %s",
+                        resp.status_code,
+                        resp.text[:200],
+                    )
+                    return False
+
+                logger.warning(
+                    "Loki push returned %d (attempt %d/%d): %s",
+                    resp.status_code,
+                    attempt,
+                    self._max_retries,
+                    resp.text[:200],
+                )
+            except httpx.HTTPError as exc:
+                logger.warning(
+                    "Loki push failed (attempt %d/%d): %s",
+                    attempt,
+                    self._max_retries,
+                    exc,
+                )
+            if attempt < self._max_retries:
+                await asyncio.sleep(self._retry_delay * (2 ** (attempt - 1)))
+        logger.error(
+            "Failed to push %d spans to Loki after %d attempts", len(spans), self._max_retries
+        )
+        return False
+
+    # ------------------------------------------------------------------
+    #  Lifecycle
+    # ------------------------------------------------------------------
+    def close_sync(self) -> None:
+        """Close the synchronous HTTP client."""
+        if self._sync_client is not None:
+            self._sync_client.close()
+            self._sync_client = None
+
+    async def close_async(self) -> None:
+        """Close the asynchronous HTTP client."""
+        if self._async_client is not None:
+            await self._async_client.aclose()
+            self._async_client = None
+
+
+# ======================================================================
+#  Internal helpers
+# ======================================================================
+
+
+def _build_loki_payload(spans: List[TraceSpan]) -> Dict[str, Any]:
+    """Build a Loki push-API payload from a batch of spans.
+
+    Groups spans by (project, kind) to minimise stream count.
+    Timestamps are string nanoseconds (Loki requirement).
+    Structured metadata carries trace_id/span_id/run_id for Loki >=3.0;
+    the same data is in the JSON body for users on older Loki with ``| json``.
+    """
+    groups: Dict[tuple, List[tuple]] = {}
+    for span in spans:
+        key = (span.project, span.kind.value)
+        ts_ns = str(int(span.start_time * 1_000_000_000))
+        line = span.to_json()
+        meta = {
+            "trace_id": span.trace_id,
+            "span_id": span.span_id,
+            "run_id": span.run_id,
+        }
+        if span.parent_span_id:
+            meta["parent_span_id"] = span.parent_span_id
+        groups.setdefault(key, []).append((ts_ns, line, meta))
+
+    streams = []
+    for (project, kind), values in groups.items():
+        streams.append(
+            {
+                "stream": {**_STATIC_LABELS, "project": project, "kind": kind},
+                "values": values,
+            }
+        )
+    return {"streams": streams}

agentgraf-0.1.0/src/agentgraf/models.py

@@ -0,0 +1,165 @@
+"""AgentGraf data models — Pydantic v2 span representation for LLM agent traces.
+
+All timestamps are float unix-epoch seconds (compatible with Loki nanosecond push).
+The model mirrors OpenTelemetry conventions where possible so that future
+exporters (OTLP, Jaeger, Zipkin) are trivial to add.
+
+contract-version: 1
+"""
+from __future__ import annotations
+
+import time
+import uuid
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class SpanKind(str, Enum):
+    """OpenTelemetry SpanKind adapted for LLM workloads."""
+
+    LLM = "llm"
+    TOOL = "tool"
+    CHAIN = "chain"
+    AGENT = "agent"
+    RETRIEVER = "retriever"
+
+
+class SpanStatus(str, Enum):
+    OK = "ok"
+    ERROR = "error"
+
+
+class TraceSpan(BaseModel):
+    """A single span in an AI-agent trace.
+
+    This is the stable data contract — backward compatible for life.
+    Fields mirror OpenTelemetry conventions where possible.
+
+    Attributes:
+        trace_id: 32-hex-char UUID, shared by all spans in one logical run.
+        span_id: 16-hex-char UUID, unique per span.
+        parent_span_id: 16-hex-char UUID or ``None`` for root spans.
+        run_id: Stable ID across a full agent invocation (LangChain ``run_id``).
+        run_name: Optional human-readable label for the run.
+        project: Logical grouping (e.g. ``k-fix``, ``support-bot``).
+        kind: Semantic classification of the span.
+        name: Human-readable operation name (``gpt-4o``, ``kubectl_get_pods``).
+        start_time: Unix-epoch seconds.
+        end_time: Unix-epoch seconds (``None`` until span is closed).
+        latency_ms: Computed from (end_time - start_time) * 1000.
+        model: LLM model name (OpenAI, Anthropic, etc.).
+        input_tokens: Token count consumed by the prompt.
+        output_tokens: Token count produced by the completion.
+        total_tokens: ``input_tokens + output_tokens``.
+        input_data: Truncated/sanitized input payload (JSON string).
+        output_data: Truncated/sanitized output payload (JSON string).
+        status: ``"ok"`` or ``"error"``.
+        error: Error message when status is ``"error"``.
+        tags: Free-form key/value labels.
+        metadata: Structured metadata (extensible).
+        agentgraf_version: Protocol version (current = 1).
+    """
+
+    # ── OTel-compatible IDs ──
+    trace_id: str = Field(
+        default_factory=lambda: uuid.uuid4().hex,
+        description="32-char hex (OTel format)",
+    )
+    span_id: str = Field(
+        default_factory=lambda: uuid.uuid4().hex[:16],
+        description="16-char hex",
+    )
+    parent_span_id: Optional[str] = Field(
+        default=None,
+        description="16-char hex or None (root span)",
+    )
+
+    # ── Identification ──
+    run_id: str = Field(
+        default_factory=lambda: uuid.uuid4().hex[:16],
+        description="Stable across a full agent invocation",
+    )
+    run_name: Optional[str] = None
+    project: str = "default"
+
+    # ── Span metadata ──
+    kind: SpanKind = SpanKind.CHAIN
+    name: str = "unnamed"
+    start_time: float = Field(default_factory=time.time)
+    end_time: Optional[float] = None
+    latency_ms: Optional[int] = None
+
+    # ── LLM-specific ──
+    model: Optional[str] = None
+    input_tokens: int = 0
+    output_tokens: int = 0
+    total_tokens: int = 0
+
+    # ── I/O (sanitized, truncated) ──
+    input_data: Optional[str] = None
+    output_data: Optional[str] = None
+
+    # ── Status ──
+    status: SpanStatus = SpanStatus.OK
+    error: Optional[str] = None
+
+    # ── Extensibility ──
+    tags: Dict[str, Any] = Field(default_factory=dict)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+    # ── AgentGraf protocol version ──
+    agentgraf_version: int = 1
+
+    # ------------------------------------------------------------------
+    #  Life-cycle helpers
+    # ------------------------------------------------------------------
+    def finish(
+        self,
+        end_time: Optional[float] = None,
+        status: Optional[SpanStatus] = None,
+        error: Optional[str] = None,
+    ) -> "TraceSpan":
+        """Close the span, recording end_time, latency, and optional status."""
+        self.end_time = end_time or time.time()
+        self.latency_ms = int((self.end_time - self.start_time) * 1000)
+        if status is not None:
+            self.status = status
+        if error is not None:
+            self.error = error
+        return self
+
+    def set_tag(self, key: str, value: Any) -> "TraceSpan":
+        """Fluent helper to add a single tag."""
+        self.tags[key] = value
+        return self
+
+    def set_metadata(self, key: str, value: Any) -> "TraceSpan":
+        """Fluent helper to add a single metadata entry."""
+        self.metadata[key] = value
+        return self
+
+    def set_input(self, data: str, truncate: int = 10_000) -> "TraceSpan":
+        """Set input_data with optional truncation."""
+        self.input_data = data[:truncate] if len(data) > truncate else data
+        return self
+
+    def set_output(self, data: str, truncate: int = 10_000) -> "TraceSpan":
+        """Set output_data with optional truncation."""
+        self.output_data = data[:truncate] if len(data) > truncate else data
+        return self
+
+    def set_tokens(self, input_tokens: int, output_tokens: int) -> "TraceSpan":
+        """Record token usage."""
+        self.input_tokens = input_tokens
+        self.output_tokens = output_tokens
+        self.total_tokens = input_tokens + output_tokens
+        return self
+
+    # ------------------------------------------------------------------
+    #  Serialization
+    # ------------------------------------------------------------------
+    def to_json(self) -> str:
+        """Compact JSON string (one line → friendly for Loki / stdout)."""
+        return self.model_dump_json(exclude_none=True)