agentrail-python 0.1.0__py3-none-any.whl

agentrail_python/_init.py

@@ -0,0 +1,64 @@
+# Copyright 2026 Agentrail. Licensed under the Apache License, Version 2.0.
+"""Standalone startup: Agentrail owns the process's OpenTelemetry providers."""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import replace
+
+from opentelemetry import _logs as otel_logs
+from opentelemetry import propagate, trace
+from opentelemetry._logs._internal import ProxyLoggerProvider  # pyright: ignore[reportPrivateImportUsage]
+from opentelemetry.sdk._logs import LoggerProvider
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.sampling import ALWAYS_ON
+
+from ._client import Client
+from ._options import ConfigurationError, Options
+from ._processors import Processors
+
+_lock = threading.Lock()
+_installed: tuple[Options, Client] | None = None
+
+
+def init(options: Options) -> Client:
+    """Install Agentrail's tracer provider, logger provider and propagator globally.
+
+    Call once at startup, before the application serves requests. The
+    providers drain when the interpreter exits; call ``shutdown`` yourself after
+    your server stops accepting requests to bound it. Calling it
+    again with the same options object returns the same client. If the process
+    already has an OpenTelemetry provider, build it with ``create_processors``
+    instead.
+    """
+    global _installed
+    with _lock:
+        if _installed is not None:
+            if _installed[0] is not options:
+                raise ConfigurationError("Agentrail is already initialized. Reuse the original options and client.")
+            return _installed[1]
+        if not isinstance(trace.get_tracer_provider(), trace.ProxyTracerProvider):
+            raise ConfigurationError(
+                "A tracer provider is already installed. Wire create_processors into its construction instead."
+            )
+        if not isinstance(otel_logs.get_logger_provider(), ProxyLoggerProvider):
+            raise ConfigurationError(
+                "A logger provider is already installed. Use create_processors with the existing setup."
+            )
+        processors = Processors(options if options.propagator is not None else _with_base(options))
+        provider = TracerProvider(sampler=processors.sampler(ALWAYS_ON))
+        provider.add_span_processor(processors.span_processor)
+        logger = LoggerProvider()
+        logger.add_log_record_processor(processors.log_processor)
+        client = processors.bind(provider)
+        trace.set_tracer_provider(provider)
+        otel_logs.set_logger_provider(logger)
+        propagate.set_global_textmap(processors.propagator)
+        client._on_shutdown.extend((provider.shutdown, logger.shutdown))  # pyright: ignore[reportPrivateUsage]
+        _installed = (options, client)
+        return client
+
+
+def _with_base(options: Options) -> Options:
+    """Unmanaged work keeps the process's existing propagator."""
+    return replace(options, propagator=propagate.get_global_textmap())

agentrail_python/_options.py

@@ -0,0 +1,305 @@
+# Copyright 2026 Agentrail. Licensed under the Apache License, Version 2.0.
+"""Public configuration and evidence types, and their validation."""
+
+from __future__ import annotations
+
+import re
+import sys
+import uuid
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Literal
+from urllib.parse import SplitResult, urlsplit
+
+from ._text import valid_text, well_formed
+
+if TYPE_CHECKING:
+    from opentelemetry.propagators.textmap import TextMapPropagator
+
+PrincipalKind = Literal["user", "agent_registration", "agent_instance", "oauth_client", "api_key"]
+PRINCIPAL_KINDS: frozenset[str] = frozenset(("user", "agent_registration", "agent_instance", "oauth_client", "api_key"))
+Surface = Literal["http", "mcp", "auth", "custom", "a2a", "genai", "payment", "edge", "firewall", "browser"]
+SURFACES: frozenset[str] = frozenset(
+    ("http", "mcp", "auth", "custom", "a2a", "genai", "payment", "edge", "firewall", "browser")
+)
+LocationSource = Literal["dbip", "cloudflare", "vercel", "source"]
+LOCATION_SOURCES: frozenset[str] = frozenset(("dbip", "cloudflare", "vercel", "source"))
+
+CaptureCode = Literal[
+    "queue_full",
+    "export_failed",
+    "deadline",
+    "closed",
+    "handoff_refused",
+    "entry_not_recording",
+    "location_failed",
+    "ignore_failed",
+    "identity_outside_request",
+    "invalid_performance",
+]
+Signal = Literal["traces", "logs", "context"]
+
+
+class ConfigurationError(ValueError):
+    """Options, identity or milestone input the SDK cannot use."""
+
+
+class CaptureError(Exception):
+    """Lost records or refused context. Holds no customer data.
+
+    Passed to ``on_error``; the SDK never raises it into the application.
+    """
+
+    def __init__(self, code: CaptureCode, signal: Signal, count: int) -> None:
+        super().__init__(f"Agentrail {signal} capture: {code} ({count} records).")
+        self.code: CaptureCode = code
+        self.signal: Signal = signal
+        self.count = count
+
+
+@dataclass(frozen=True, kw_only=True)
+class CollectorOptions:
+    """The collector's OTLP base URL and a backend source secret."""
+
+    endpoint: str
+    secret: str
+
+
+@dataclass(frozen=True, kw_only=True)
+class QueueOptions:
+    """Per-signal delivery bounds. Times are seconds."""
+
+    max_records: int = 2048
+    batch_size: int = 128
+    scheduled_delay: float = 1.0
+    export_timeout: float = 5.0
+    flush_timeout: float = 10.0
+    shutdown_timeout: float = 10.0
+
+
+@dataclass(frozen=True, kw_only=True)
+class LogsOptions:
+    """Message text and other fields leave only when named in ``include_fields``."""
+
+    include_fields: Sequence[str] = ()
+    exclude_uncorrelated: bool = False
+
+
+@dataclass(frozen=True, kw_only=True)
+class IPLocation:
+    """An approximate network exit, never a verified place. ``None`` is unknown."""
+
+    country: str | None = None
+    region: str | None = None
+    city: str | None = None
+    source: LocationSource = "source"
+
+
+@dataclass(frozen=True)
+class IncomingRequest:
+    """What the hooks see of an incoming request.
+
+    ``headers`` has lowercase names; a repeated header's values are joined with
+    ``", "``. ``client`` is the peer address the server saw, not a forwarded
+    header. ``raw`` is the ASGI scope or the WSGI environ.
+    """
+
+    method: str
+    target: str
+    scheme: str
+    host: str
+    headers: Mapping[str, str]
+    client: str | None
+    raw: Mapping[str, object]
+
+
+@dataclass(frozen=True, kw_only=True)
+class Options:
+    collector: CollectorOptions
+    hash_key: str
+    service_name: str
+    service_instance_id: str | None = None
+    outbound_origins: Sequence[str] = ()
+    ignore_incoming_request: Callable[[IncomingRequest], bool] | None = None
+    incoming_location: Callable[[IncomingRequest], IPLocation | None] | None = None
+    logs: LogsOptions = field(default_factory=LogsOptions)
+    queue: QueueOptions = field(default_factory=QueueOptions)
+    propagator: TextMapPropagator | None = None
+    on_error: Callable[[CaptureError], None] | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class VerifiedIdentity:
+    """An identity the application has already authenticated."""
+
+    kind: PrincipalKind
+    id: str
+    acting_user_id: str | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class McpContext:
+    method: str
+    client: str | None = None
+    client_version: str | None = None
+    protocol: str | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class AuthorizedOperation:
+    """A business attempt the application has authorized.
+
+    ``instance_ref`` is hashed locally and never exported.
+    """
+
+    namespace_id: str
+    instance_ref: str
+    role: Literal["start", "progress", "terminal"]
+
+
+@dataclass(frozen=True, kw_only=True)
+class PluginInvocation:
+    """``invocation_id`` is opaque: never tool arguments or a customer identifier."""
+
+    binding_id: str
+    invocation_id: str
+
+
+@dataclass(frozen=True, kw_only=True)
+class PerformanceContext:
+    """Workflow and plugin evidence. Supply ``operation`` with ``event_name``,
+    ``operation`` with ``plugin``, or ``plugin`` alone."""
+
+    environment: Literal["production", "test"]
+    operation: AuthorizedOperation | None = None
+    event_name: str | None = None
+    plugin: PluginInvocation | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class MilestoneContext:
+    surface: Surface
+    kind: str
+    mcp: McpContext | None = None
+    performance: PerformanceContext | None = None
+
+
+@dataclass(frozen=True)
+class Resolved:
+    """Validated options with derived values."""
+
+    input: Options
+    endpoint: str
+    endpoint_origin: str
+    endpoint_path: str
+    instance: str
+    origins: frozenset[str]
+    queue: QueueOptions
+    include_fields: tuple[str, ...]
+
+    def report(self, error: CaptureError) -> None:
+        from ._suppression import reporting
+
+        with reporting():
+            callback = self.input.on_error
+            if callback is None:
+                print(error, file=sys.stderr)
+                return
+            try:
+                callback(error)
+            except Exception as callback_error:  # noqa: BLE001 - an application callback may raise anything
+                print("Agentrail on_error callback failed:", repr(callback_error), error, file=sys.stderr)
+
+
+def origin_of(parts: SplitResult) -> str:
+    """Lowercase scheme and host, IPv6 in brackets, default port omitted."""
+    scheme = parts.scheme.lower()
+    host = (parts.hostname or "").lower()
+    if ":" in host:
+        host = f"[{host}]"
+    port = parts.port
+    if port is not None and not ((scheme == "http" and port == 80) or (scheme == "https" and port == 443)):
+        host = f"{host}:{port}"
+    return f"{scheme}://{host}"
+
+
+def _url(value: str) -> SplitResult | None:
+    try:
+        parts = urlsplit(value)
+        _ = parts.port  # raises for an invalid port
+    except ValueError:
+        return None
+    if parts.scheme.lower() not in ("http", "https") or not parts.hostname:
+        return None
+    if parts.username is not None or parts.password is not None:
+        return None
+    if parts.query or parts.fragment or "?" in value or "#" in value:
+        return None
+    return parts
+
+
+def resolve(options: Options) -> Resolved:
+    endpoint = _url(options.collector.endpoint)
+    if endpoint is None:
+        raise ConfigurationError("Use an absolute http(s) collector base URL without credentials, query or fragment.")
+    secret = options.collector.secret
+    if (
+        not options.hash_key
+        or not well_formed(options.hash_key)
+        or not secret
+        or any(character in secret for character in " \t\r\n")
+        or not options.service_name
+        or not valid_text(options.service_name, 4096)
+        or (options.service_instance_id is not None and not options.service_instance_id)
+        or (options.service_instance_id is not None and not valid_text(options.service_instance_id, 4096))
+    ):
+        raise ConfigurationError(
+            "Configure a source secret, a UTF-8 workspace hash key and a service name "
+            "(and instance ID) of well-formed text without NUL, at most 4096 characters."
+        )
+    queue = options.queue
+    integers = (queue.max_records, queue.batch_size)
+    times = (queue.scheduled_delay, queue.export_timeout, queue.flush_timeout, queue.shutdown_timeout)
+    if (
+        any(isinstance(value, bool) or value < 1 for value in integers)
+        or any(isinstance(value, bool) or not value > 0 for value in times)
+        or queue.batch_size > queue.max_records
+        or queue.batch_size > 10_000
+        or queue.export_timeout > min(queue.flush_timeout, queue.shutdown_timeout)
+    ):
+        raise ConfigurationError(
+            "Use positive queue limits, batch_size <= max_records and 10000, "
+            "and flush/shutdown timeouts >= export_timeout."
+        )
+    origins: set[str] = set()
+    for raw in options.outbound_origins:
+        parts = _url(raw)
+        if parts is None or parts.path != "" or origin_of(parts) != raw:
+            raise ConfigurationError("outbound_origins must contain exact canonical http(s) origins.")
+        origins.add(raw)
+    for name in options.logs.include_fields:
+        if not isinstance(name, str):  # pyright: ignore[reportUnnecessaryIsInstance]
+            raise ConfigurationError("logs.include_fields must contain field names.")
+    trimmed = options.collector.endpoint.rstrip("/")
+    return Resolved(
+        input=options,
+        endpoint=trimmed,
+        endpoint_origin=origin_of(endpoint),
+        endpoint_path=endpoint.path.rstrip("/"),
+        instance=options.service_instance_id or uuid.uuid4().hex,
+        origins=frozenset(origins),
+        queue=queue,
+        include_fields=tuple(options.logs.include_fields),
+    )
+
+
+_UUID = re.compile(r"[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}")
+_EVENT = re.compile(r"[a-zA-Z][a-zA-Z0-9_.:-]*")
+
+
+def valid_uuid(value: str) -> bool:
+    return _UUID.fullmatch(value) is not None
+
+
+def valid_event_name(value: str) -> bool:
+    return len(value) <= 120 and _EVENT.fullmatch(value) is not None

agentrail_python/_outbound.py

@@ -0,0 +1,76 @@
+# Copyright 2026 Agentrail. Licensed under the Apache License, Version 2.0.
+"""What an outgoing call carries, decided by its actual destination."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from opentelemetry.trace import Span, SpanKind, StatusCode
+
+from ._handoff import HANDOFF_HEADER, HandoffInputError, format_traceparent, sign
+
+if TYPE_CHECKING:
+    from ._client import Client
+
+
+def origin(scheme: str, host: str, port: int | None) -> str:
+    scheme = scheme.lower()
+    host = host.lower()
+    if ":" in host and not host.startswith("["):
+        host = f"[{host}]"
+    if port is not None and not ((scheme == "http" and port == 80) or (scheme == "https" and port == 443)):
+        host = f"{host}:{port}"
+    return f"{scheme}://{host}"
+
+
+@dataclass
+class Outgoing:
+    """``span`` is None when the call is not part of a managed operation."""
+
+    span: Span | None
+    headers: dict[str, str] = field(default_factory=lambda: {})
+    strip: bool = False
+
+
+def begin(client: Client, method: str, destination: str, path: str, target: str, url: str) -> Outgoing:
+    """Owned headers are always stripped from managed calls; only exact allowed
+    origins receive a newly signed handoff."""
+    runtime = client._runtime  # pyright: ignore[reportPrivateUsage]
+    if not client._managed():  # pyright: ignore[reportPrivateUsage]
+        return Outgoing(None)
+    options = runtime.options
+    if destination == options.endpoint_origin and path in (
+        f"{options.endpoint_path}/v1/traces",
+        f"{options.endpoint_path}/v1/logs",
+    ):
+        return Outgoing(None, strip=True)
+    tracer = client._tracer  # pyright: ignore[reportPrivateUsage]
+    span = tracer.start_span(
+        f"HTTP {method}",
+        kind=SpanKind.CLIENT,
+        attributes={"http.request.method": method, "url.full": url},
+    )
+    outgoing = Outgoing(span, strip=True)
+    if destination in options.origins:
+        context = span.get_span_context()
+        parent = format_traceparent(context.trace_id, context.span_id, context.trace_flags)
+        try:
+            token = sign(options.input.hash_key, parent, method, target, time.time_ns() // 1_000_000)
+        except HandoffInputError:
+            runtime.report("handoff_refused", "context")
+        else:
+            outgoing.headers = {"traceparent": parent, HANDOFF_HEADER: token}
+    return outgoing
+
+
+def finish(span: Span, status: int | None, error: BaseException | None) -> None:
+    if error is not None:
+        span.set_status(StatusCode.ERROR)
+        span.set_attribute("error.type", "TransportError")
+    if status is not None:
+        span.set_attribute("http.response.status_code", status)
+        if status >= 400:
+            span.set_status(StatusCode.ERROR)
+    span.end()

agentrail_python/_performance.py

@@ -0,0 +1,63 @@
+# Copyright 2026 Agentrail. Licensed under the Apache License, Version 2.0.
+"""Workflow and plugin evidence on a milestone, as agentrail-node emits it."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+from ._options import ConfigurationError, PerformanceContext, valid_event_name, valid_uuid
+from ._runtime import Attributes
+from ._text import js_json, utf16_length, well_formed
+
+
+def operation_hash(hash_key: str, namespace_id: str, instance_ref: str) -> str:
+    """HMAC-SHA256 of ``["agentrail.operation", namespace, reference]`` as JSON, full hex."""
+    payload = js_json(["agentrail.operation", namespace_id, instance_ref]).encode("utf-8")
+    return hmac.new(hash_key.encode("utf-8"), payload, hashlib.sha256).hexdigest()
+
+
+def performance_attributes(performance: PerformanceContext, hash_key: str) -> Attributes:
+    """Only normalized, allowlisted evidence. Raises ``ConfigurationError`` for invalid input."""
+    if performance.environment not in ("production", "test"):
+        raise ConfigurationError("Use the production or test environment.")
+    operation, plugin = performance.operation, performance.plugin
+    if plugin is None and (operation is None or performance.event_name is None):
+        raise ConfigurationError("Supply an operation with its event name, a plugin invocation, or both.")
+    if operation is None and performance.event_name is not None:
+        raise ConfigurationError("An event name needs its authorized operation.")
+    attributes: Attributes = {"agentrail.environment": performance.environment}
+    if plugin is not None:
+        invocation = plugin.invocation_id
+        if (
+            not valid_uuid(plugin.binding_id)
+            or not 1 <= utf16_length(invocation) <= 256
+            or not well_formed(invocation)
+            or "\x00" in invocation
+        ):
+            raise ConfigurationError("Use a canonical binding ID and an opaque invocation ID of 1-256 characters.")
+        attributes["agentrail.plugin.binding_id"] = plugin.binding_id
+        attributes["agentrail.plugin.invocation_id"] = invocation
+    if operation is not None:
+        if (
+            not valid_uuid(operation.namespace_id)
+            or not operation.instance_ref
+            or not well_formed(operation.instance_ref)
+            or operation.role not in ("start", "progress", "terminal")
+        ):
+            raise ConfigurationError(
+                "Use a canonical namespace ID, a nonempty well-formed operation reference and a role."
+            )
+        attributes["agentrail.operation.namespace_id"] = operation.namespace_id
+        attributes["agentrail.operation.hash"] = operation_hash(
+            hash_key, operation.namespace_id, operation.instance_ref
+        )
+        attributes["agentrail.workflow.role"] = operation.role
+        if performance.event_name is not None:
+            if not valid_event_name(performance.event_name):
+                raise ConfigurationError(
+                    "Use a business event name of 1-120 letters, digits, dots, underscores, "
+                    "colons or hyphens, starting with a letter."
+                )
+            attributes["agentrail.workflow.event_name"] = performance.event_name
+    return attributes