rootmark 0.0.1__tar.gz → 0.1.0__tar.gz

rootmark-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+venv/
+.venv/
+__pycache__/
+*.pyc
+.mypy_cache/
+dist/
+.pytest_cache/
+.coverage
+.tox/
+.ruff_cache/
+.env
+
+# MkDocs
+site/
+
+
+# migration scratch (not part of the project)
+/_to_delete_git_1786975500/
+/_pip-reserve-dist/
+
+# SDK spill-over buffers: runtime state, may contain trace payloads
+.rootmark_spillover.jsonl
+*.rootmark_spillover.jsonl
+.rootmark_spillover.jsonl.tmp
+
+# local CLI credentials
+.rootmark.env
+
+# fixed dev credentials for `make seed-project` (project ids + raw API key)
+.env.seed
+
+# scratch / build output
+/artifacts/
+/.tmp_g7_cli/
+
+# TS build output
+*.tsbuildinfo

rootmark-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: rootmark
+Version: 0.1.0
+Summary: Rootmark SDK -- agent instrumentation
+Project-URL: Homepage, https://rootmark.dev
+Project-URL: Documentation, https://rootmark.dev/docs/
+Project-URL: Source, https://github.com/IvanAdactic/rootmark
+Keywords: agents,instrumentation,llm,observability,tracing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pydantic>=2.10.0
+Provides-Extra: boto3
+Requires-Dist: boto3>=1.35.0; extra == 'boto3'
+Provides-Extra: crewai
+Requires-Dist: crewai<2,>=0.86; extra == 'crewai'
+Provides-Extra: dev
+Requires-Dist: crewai<2,>=0.86; extra == 'dev'
+Requires-Dist: langchain-core<2,>=0.3; extra == 'dev'
+Requires-Dist: openai<3,>=1.40.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core<2,>=0.3; extra == 'langchain'
+Provides-Extra: openai
+Requires-Dist: openai<3,>=1.40.0; extra == 'openai'
+Provides-Extra: strands
+Requires-Dist: strands-agents>=1.26.0; extra == 'strands'
+Description-Content-Type: text/markdown
+
+# Rootmark SDK
+
+Agent instrumentation for [Rootmark](https://rootmark.dev) — observe, verify and
+govern agent runs.
+
+The SDK records what your agents actually did: the span tree of a run, the model
+calls inside it, token counts, and the payloads you choose to keep. It sends
+them to a Rootmark collector, which you can self-host.
+
+```bash
+pip install rootmark
+```
+
+Requires Python 3.12 or newer.
+
+## Quickstart
+
+```python
+import rootmark
+
+rootmark.init(
+    api_key="pk_...",                 # project API key
+    project_id="...",                 # UUID
+    api_key_id="...",                 # UUID
+    api_url="https://rootmark.example.com",
+    workflow_name="my-service",       # not "default" -- see below
+)
+
+rootmark.patch()                      # instrument supported frameworks in place
+```
+
+That is the whole integration for the common case. `patch()` installs
+instrumentation process-wide, so call it once at startup and before the first
+agent invocation.
+
+## Grouping and labelling runs
+
+```python
+with rootmark.workflow_override("contract-review"):
+    with rootmark.bind_context(tenant_id="acme", session_id=session, tags=["surface:chat"]):
+        result = agent(prompt)
+```
+
+`bind_context` applies to everything that runs inside it, including tasks the
+agent loop spawns, because the binding follows the async context.
+
+`workflow_name` should not be `"default"`: that value lets framework
+instrumentation override the name you bind per run with its own agent id.
+
+## Framework support
+
+The base install instruments nothing on its own beyond direct use. Install the
+extra for what you actually run:
+
+```bash
+pip install "rootmark[openai]"    # OpenAI 1.x and 2.x
+pip install "rootmark[langchain]" # LangChain callback handler
+pip install "rootmark[crewai]"    # CrewAI event listeners
+pip install "rootmark[strands]"   # Strands agents / AWS Bedrock
+pip install "rootmark[boto3]"     # Bedrock via botocore, no code change
+```
+
+For boto3, a session built by hand rather than the default one needs
+`rootmark.patch_session(session)` — the botocore hooks only reach the default
+session otherwise.
+
+## Delivery
+
+Spans are batched on a background thread and flushed on a timer, so nothing
+blocks a request. A failed export is written to a spill file and retried,
+keeping its batch identity so the collector can recognise a replay rather than
+double-count it. Ordering is preserved: a batch that cannot be delivered holds
+back the ones behind it.
+
+Point `spill_file` somewhere writable. The default is relative to the working
+directory, which in a container is frequently owned by root while the process
+runs as someone else — and a spill file that cannot be written is buffering you
+silently do not have.
+
+Call `rootmark.flush()` before a process exits if you want outstanding spans
+delivered, and `rootmark.shutdown()` to stop the processor.
+
+## Keeping payloads out
+
+```python
+rootmark.init(..., suppress_payloads=True)
+```
+
+Spans are still recorded — timings, token counts, the shape of the run — but
+prompt and completion text is not sent. Use this when the collector sits outside
+the trust boundary that the data does not leave.
+
+## Links
+
+- Documentation: <https://rootmark.dev/docs/>
+- Source: <https://github.com/IvanAdactic/rootmark>

rootmark-0.1.0/README.md

@@ -0,0 +1,96 @@
+# Rootmark SDK
+
+Agent instrumentation for [Rootmark](https://rootmark.dev) — observe, verify and
+govern agent runs.
+
+The SDK records what your agents actually did: the span tree of a run, the model
+calls inside it, token counts, and the payloads you choose to keep. It sends
+them to a Rootmark collector, which you can self-host.
+
+```bash
+pip install rootmark
+```
+
+Requires Python 3.12 or newer.
+
+## Quickstart
+
+```python
+import rootmark
+
+rootmark.init(
+    api_key="pk_...",                 # project API key
+    project_id="...",                 # UUID
+    api_key_id="...",                 # UUID
+    api_url="https://rootmark.example.com",
+    workflow_name="my-service",       # not "default" -- see below
+)
+
+rootmark.patch()                      # instrument supported frameworks in place
+```
+
+That is the whole integration for the common case. `patch()` installs
+instrumentation process-wide, so call it once at startup and before the first
+agent invocation.
+
+## Grouping and labelling runs
+
+```python
+with rootmark.workflow_override("contract-review"):
+    with rootmark.bind_context(tenant_id="acme", session_id=session, tags=["surface:chat"]):
+        result = agent(prompt)
+```
+
+`bind_context` applies to everything that runs inside it, including tasks the
+agent loop spawns, because the binding follows the async context.
+
+`workflow_name` should not be `"default"`: that value lets framework
+instrumentation override the name you bind per run with its own agent id.
+
+## Framework support
+
+The base install instruments nothing on its own beyond direct use. Install the
+extra for what you actually run:
+
+```bash
+pip install "rootmark[openai]"    # OpenAI 1.x and 2.x
+pip install "rootmark[langchain]" # LangChain callback handler
+pip install "rootmark[crewai]"    # CrewAI event listeners
+pip install "rootmark[strands]"   # Strands agents / AWS Bedrock
+pip install "rootmark[boto3]"     # Bedrock via botocore, no code change
+```
+
+For boto3, a session built by hand rather than the default one needs
+`rootmark.patch_session(session)` — the botocore hooks only reach the default
+session otherwise.
+
+## Delivery
+
+Spans are batched on a background thread and flushed on a timer, so nothing
+blocks a request. A failed export is written to a spill file and retried,
+keeping its batch identity so the collector can recognise a replay rather than
+double-count it. Ordering is preserved: a batch that cannot be delivered holds
+back the ones behind it.
+
+Point `spill_file` somewhere writable. The default is relative to the working
+directory, which in a container is frequently owned by root while the process
+runs as someone else — and a spill file that cannot be written is buffering you
+silently do not have.
+
+Call `rootmark.flush()` before a process exits if you want outstanding spans
+delivered, and `rootmark.shutdown()` to stop the processor.
+
+## Keeping payloads out
+
+```python
+rootmark.init(..., suppress_payloads=True)
+```
+
+Spans are still recorded — timings, token counts, the shape of the run — but
+prompt and completion text is not sent. Use this when the collector sits outside
+the trust boundary that the data does not leave.
+
+## Links
+
+- Documentation: <https://rootmark.dev/docs/>
+- Source: <https://github.com/IvanAdactic/rootmark>

rootmark-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "rootmark"
+version = "0.1.0"
+description = "Rootmark SDK -- agent instrumentation"
+readme = "README.md"
+requires-python = ">=3.12"
+# No licence declared for 0.1.0; to be added in a later release.
+keywords = ["agents", "observability", "tracing", "llm", "instrumentation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Monitoring",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.10.0",
+    "httpx>=0.28.0",
+]
+
+[project.urls]
+Homepage = "https://rootmark.dev"
+Documentation = "https://rootmark.dev/docs/"
+Source = "https://github.com/IvanAdactic/rootmark"
+
+[project.optional-dependencies]
+# OpenAI integration (Group 4); tested with 1.x and 2.x
+openai = ["openai>=1.40.0,<3"]
+# LangChain callback handler (D4.7); BaseCallbackHandler is stable across 0.3.x and 1.x
+langchain = ["langchain-core>=0.3,<2"]
+# CrewAI event listeners (D5.6); BaseEventListener + crewai_event_bus (tested 0.86–1.x)
+crewai = ["crewai>=0.86,<2"]
+# Strands SDK / AWS Bedrock agent patch (D6.1)
+strands = ["strands-agents>=1.26.0"]
+# Boto3 / botocore interceptor for Bedrock zero-code-change path (D6.3)
+boto3 = ["boto3>=1.35.0"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.24", "openai>=1.40.0,<3", "langchain-core>=0.3,<2", "crewai>=0.86,<2"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rootmark"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+markers = [
+    "integration: needs docker-compose (API, worker, ClickHouse, Postgres)",
+]
+

rootmark-0.1.0/src/rootmark/__init__.py

@@ -0,0 +1,234 @@
+"""Rootmark SDK -- agent instrumentation for behavioral testing."""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from collections.abc import Callable
+from contextlib import contextmanager
+from functools import wraps
+from typing import Any, TypeVar
+
+from rootmark.config import (
+    RootmarkConfig,
+    config_override,
+    config_override_sync,
+    flush,
+    get_config,
+    get_processor,
+    init,
+    shutdown,
+)
+from rootmark.core.emitter import (
+    SpanContext,
+    SpanEmitter,
+    add_span_tags,
+    bind_context,
+    get_ambient_context,
+    merge_span_extra,
+    reset_span_context,
+    workflow_override,
+)
+from rootmark.patches import apply_patches
+from rootmark.schema import RunType, SpanStatus, TokenCount, TraceEvent
+
+logger = logging.getLogger(__name__)
+
+__version__ = "0.1.0"
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+_PATCHED = False
+
+
+def patch() -> None:
+    """Activate optional integrations (OpenAI, ...). Idempotent."""
+    global _PATCHED
+    if _PATCHED:
+        return
+    _PATCHED = True
+    apply_patches()
+
+
+def fork_context():
+    """Copy the current span context for use in a parallel branch.
+
+    Delegates to :meth:`SpanEmitter.fork_context`.  Use when spawning
+    threads or executor tasks that should inherit the current trace
+    parentage without sharing mutable ContextVar state.
+    """
+    return SpanEmitter.fork_context()
+
+
+def patch_session(boto3_session: object) -> None:
+    """Register the Bedrock interceptor on a specific ``boto3.Session``.
+
+    Use this for multi-session applications where different sessions have
+    different credentials or regions.  Idempotent per session instance.
+    """
+    from rootmark.patches.boto3_interceptor import patch_session as _ps
+
+    _ps(boto3_session)
+
+
+def _safe_serialize(obj: Any, max_len: int = 8000) -> Any:
+    try:
+        if obj is None or isinstance(obj, (bool, int, float)):
+            return obj
+        if isinstance(obj, str):
+            return obj if len(obj) <= max_len else obj[:max_len] + "...(truncated)"
+        r = repr(obj)
+        return r if len(r) <= max_len else r[:max_len] + "...(truncated)"
+    except Exception:
+        return "<unserializable>"
+
+
+def _fn_inputs(fn: Callable[..., Any], args: tuple[Any, ...], kwargs: dict[str, Any]) -> dict[str, Any]:
+    try:
+        sig = inspect.signature(fn)
+        bound = sig.bind_partial(*args, **kwargs)
+        bound.apply_defaults()
+        return {k: _safe_serialize(v) for k, v in bound.arguments.items()}
+    except Exception:
+        return {"args": _safe_serialize(args), "kwargs": _safe_serialize(kwargs)}
+
+
+def trace(workflow: str | None = None) -> Callable[[F], F]:
+    """
+    Decorator: one root ``AGENT`` span per function invocation, with optional workflow name.
+
+    Supports sync and async callables. Clears span context so each call is a new trace.
+    """
+
+    def decorator(fn: F) -> F:
+        if inspect.iscoroutinefunction(fn):
+
+            @wraps(fn)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                reset_span_context()
+                with workflow_override(workflow):
+                    inputs = _fn_inputs(fn, args, kwargs)
+                    ctx = SpanEmitter.start_span(RunType.AGENT, fn.__name__, {"inputs": inputs})
+                    try:
+                        result = await fn(*args, **kwargs)
+                        SpanEmitter.end_span(
+                            ctx,
+                            {"return": _safe_serialize(result)},
+                            SpanStatus.SUCCESS,
+                        )
+                        return result
+                    except Exception as e:
+                        SpanEmitter.end_span(ctx, {}, SpanStatus.ERROR, str(e))
+                        raise
+
+            return async_wrapper  # type: ignore[return-value]
+
+        @wraps(fn)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            reset_span_context()
+            with workflow_override(workflow):
+                inputs = _fn_inputs(fn, args, kwargs)
+                ctx = SpanEmitter.start_span(RunType.AGENT, fn.__name__, {"inputs": inputs})
+                try:
+                    result = fn(*args, **kwargs)
+                    SpanEmitter.end_span(
+                        ctx,
+                        {"return": _safe_serialize(result)},
+                        SpanStatus.SUCCESS,
+                    )
+                    return result
+                except Exception as e:
+                    SpanEmitter.end_span(ctx, {}, SpanStatus.ERROR, str(e))
+                    raise
+
+        return sync_wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+@contextmanager
+def span(
+    name: str,
+    *,
+    run_type: RunType,
+    inputs: dict[str, Any] | None = None,
+    tags: list[str] | None = None,
+):
+    """
+    Context manager: one child span (``name``, ``run_type``) around a block of code.
+
+    Example: ``with rootmark.span("search", run_type=RunType.TOOL): ...``
+
+    ``tags`` are flat labels the trace list can filter on (B2). Prefer them
+    over ``extra`` for anything you want to *search by*: tags are a real
+    column, while ``extra`` is stored as unindexed JSON text.
+    """
+    ctx = SpanEmitter.start_span(run_type, name, inputs, tags=tags)
+    try:
+        yield ctx
+    except Exception as e:
+        SpanEmitter.end_span(ctx, {}, SpanStatus.ERROR, str(e))
+        raise
+    SpanEmitter.end_span(ctx, {}, SpanStatus.SUCCESS)
+
+
+def set_span_tags(tags: list[str]) -> None:
+    """Attach filterable tags to the innermost open span before it ends.
+
+    Companion to :func:`set_span_extra` for the case where the value is a label
+    you want to *find traces by* -- an incident id, a customer tier, a release
+    channel. Tags land in the ``tags`` column and drive the trace list's tag
+    filter; ``extra`` is stored as JSON text and is not indexed.
+
+    Duplicates are collapsed, so calling this repeatedly is safe.
+    """
+    try:
+        if get_config() is None:
+            return
+        add_span_tags(list(tags))
+    except Exception:
+        logger.debug("rootmark: set_span_tags failed", exc_info=True)
+
+
+def set_span_extra(extra: dict[str, Any]) -> None:
+    """Attach additional metadata to the innermost open span before it ends.
+
+    This is a best-effort helper for injecting application-level metadata
+    (e.g., cost calculations, tenant IDs, ``session_id``) into traces.
+    Values are merged when the span closes; ``session_id`` is promoted to the
+    top-level :class:`TraceEvent` field (not kept in ``extra``).
+    """
+    try:
+        if get_config() is None:
+            return
+        merge_span_extra(extra)
+    except Exception:
+        logger.debug("rootmark.set_span_extra: failed to set extra", exc_info=True)
+
+
+__all__ = [
+    "RootmarkConfig",
+    "RunType",
+    "SpanContext",
+    "SpanEmitter",
+    "SpanStatus",
+    "TokenCount",
+    "TraceEvent",
+    "bind_context",
+    "config_override",
+    "config_override_sync",
+    "flush",
+    "fork_context",
+    "get_ambient_context",
+    "get_config",
+    "get_processor",
+    "init",
+    "patch",
+    "patch_session",
+    "set_span_extra",
+    "set_span_tags",
+    "shutdown",
+    "span",
+    "trace",
+    "workflow_override",
+]

rootmark-0.1.0/src/rootmark/audit/__init__.py

@@ -0,0 +1,5 @@
+"""Audit-layer helpers (hash-chain canonical JSON, etc.)."""
+
+from rootmark.audit.hashing import canonical_json, compute_batch_hash
+
+__all__ = ["canonical_json", "compute_batch_hash"]

rootmark-0.1.0/src/rootmark/audit/hashing.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+
+def canonical_json(obj: Any) -> bytes:
+    return json.dumps(
+        obj,
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+        default=str,
+    ).encode("utf-8")
+
+
+def compute_batch_hash(events_payload: list[dict[str, Any]]) -> str:
+    """SHA-256 hex digest over canonical JSON of the events list."""
+    return hashlib.sha256(canonical_json(events_payload)).hexdigest()