tracectrl-enterprise 0.1.0__tar.gz

tracectrl_enterprise-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+
+# Node
+node_modules/
+ui/dist/
+
+# Environment
+.env
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Docker
+clickhouse-data/
+
+# Internal planning docs (docs/ itself IS tracked — it's the shared team+agent docs)
+docs/launch-plan.md
+docs/meetings-actionables-for-launch.md
+docs/licensing-study.md
+docs/*.pdf
+
+# Agent skills (installed via `skills add`)
+.agents/
+.claude/
+.kiro/
+skills/
+skills-lock.json
+
+videos/
+.mcp.json
+
+# Personal Folder
+dylan-todo/
+
+# OCB-generated collector distribution (built from collector/builder-config.yaml)
+collector/_build/

tracectrl_enterprise-0.1.0/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 CloudsineAI
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

tracectrl_enterprise-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: tracectrl-enterprise
+Version: 0.1.0
+Summary: TraceCtrl Enterprise SDK — agentic AI security observability for the enterprise platform
+Project-URL: Homepage, https://tracectrl.ai
+Project-URL: Repository, https://github.com/tracectrl/tracectrl-enterprise
+Project-URL: Documentation, https://github.com/tracectrl/tracectrl-enterprise/blob/main/sdk/tracectrl-enterprise/README.md
+Author: CloudsineAI
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agents,ai,observability,opentelemetry,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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.10
+Requires-Dist: tracectrl<0.4,>=0.3
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tracectrl-enterprise
+
+TraceCtrl Enterprise SDK — instrument your agentic AI application to send traces
+to a TraceCtrl Enterprise deployment.
+
+Apache 2.0 licensed. Thin wrapper over the OSS [`tracectrl`](https://pypi.org/project/tracectrl/)
+package — `tracectrl` does the OpenTelemetry SDK heavy lifting; this package
+adds enterprise-specific defaults (collector endpoint, required ingest-key
+auth, fail-loud behaviour) and the `tag_agent()` API for self-identifying
+agent spans.
+
+## Install
+
+```bash
+pip install tracectrl-enterprise
+```
+
+## Quickstart
+
+```python
+import os
+from tracectrl_enterprise import configure, tag_agent
+
+configure(ingest_key=os.environ["TRACECTRL_INGEST_KEY"])
+
+@tag_agent(
+    id="payment-bot",
+    name="PaymentAgent",
+    framework="strands",  # framework you're running on; informational
+    role="payment_processing",
+)
+def run_payment(query: str) -> str:
+    # ... your agent logic ...
+    return "ok"
+```
+
+Every call to `run_payment` creates an OpenTelemetry span with the canonical
+TraceCtrl attributes (`openinference.span.kind=AGENT`,
+`tracectrl.agent.id`, `tracectrl.agent.name`, etc.), exported via OTLP/gRPC
+with `Authorization: Bearer <ingest_key>` to your TraceCtrl Enterprise
+collector. The collector resolves your ingest key to a tenant and stamps
+`tracectrl.tenant_id` on every span — your SDK doesn't (and can't) set
+tenancy itself; the collector is the trust boundary.
+
+## Configuration
+
+`configure(ingest_key=..., endpoint=..., service_name=...)` accepts:
+
+| Argument | Env var | Default | Required |
+|---|---|---|---|
+| `ingest_key` | `TRACECTRL_INGEST_KEY` | — | **yes** — fails loud if not set |
+| `endpoint` | `TRACECTRL_ENDPOINT` | `https://app.tracectrl.ai/ingest` | no |
+| `service_name` | `TRACECTRL_SERVICE_NAME` | `tracectrl-agent` | no |
+
+If you call `configure()` without an `ingest_key` argument, it reads
+`TRACECTRL_INGEST_KEY` from the environment. If neither is set, it raises
+`ValueError` — unlike the OSS SDK which can be configured to fail silently,
+enterprise installs always fail loud on missing auth.
+
+## Framework instrumentation
+
+For automatic tracing of supported frameworks (Strands, etc.), install the OSS
+instrumentor package alongside this one:
+
+```bash
+pip install tracectrl-instrumentation-strands
+```
+
+The instrumentor hooks into the same global OpenTelemetry TracerProvider that
+`tracectrl-enterprise.configure()` sets up, so spans from instrumented
+framework calls are exported the same way as your `@tag_agent`-decorated
+functions.
+
+## License
+
+Apache 2.0. The TraceCtrl Enterprise server-side platform (engine, collector,
+UI) is BUSL-licensed; the SDK is permissively licensed so it can be
+embedded in your proprietary code without restriction.
+
+## Reporting issues
+
+https://github.com/tracectrl/tracectrl-enterprise/issues

tracectrl_enterprise-0.1.0/README.md

@@ -0,0 +1,82 @@
+# tracectrl-enterprise
+
+TraceCtrl Enterprise SDK — instrument your agentic AI application to send traces
+to a TraceCtrl Enterprise deployment.
+
+Apache 2.0 licensed. Thin wrapper over the OSS [`tracectrl`](https://pypi.org/project/tracectrl/)
+package — `tracectrl` does the OpenTelemetry SDK heavy lifting; this package
+adds enterprise-specific defaults (collector endpoint, required ingest-key
+auth, fail-loud behaviour) and the `tag_agent()` API for self-identifying
+agent spans.
+
+## Install
+
+```bash
+pip install tracectrl-enterprise
+```
+
+## Quickstart
+
+```python
+import os
+from tracectrl_enterprise import configure, tag_agent
+
+configure(ingest_key=os.environ["TRACECTRL_INGEST_KEY"])
+
+@tag_agent(
+    id="payment-bot",
+    name="PaymentAgent",
+    framework="strands",  # framework you're running on; informational
+    role="payment_processing",
+)
+def run_payment(query: str) -> str:
+    # ... your agent logic ...
+    return "ok"
+```
+
+Every call to `run_payment` creates an OpenTelemetry span with the canonical
+TraceCtrl attributes (`openinference.span.kind=AGENT`,
+`tracectrl.agent.id`, `tracectrl.agent.name`, etc.), exported via OTLP/gRPC
+with `Authorization: Bearer <ingest_key>` to your TraceCtrl Enterprise
+collector. The collector resolves your ingest key to a tenant and stamps
+`tracectrl.tenant_id` on every span — your SDK doesn't (and can't) set
+tenancy itself; the collector is the trust boundary.
+
+## Configuration
+
+`configure(ingest_key=..., endpoint=..., service_name=...)` accepts:
+
+| Argument | Env var | Default | Required |
+|---|---|---|---|
+| `ingest_key` | `TRACECTRL_INGEST_KEY` | — | **yes** — fails loud if not set |
+| `endpoint` | `TRACECTRL_ENDPOINT` | `https://app.tracectrl.ai/ingest` | no |
+| `service_name` | `TRACECTRL_SERVICE_NAME` | `tracectrl-agent` | no |
+
+If you call `configure()` without an `ingest_key` argument, it reads
+`TRACECTRL_INGEST_KEY` from the environment. If neither is set, it raises
+`ValueError` — unlike the OSS SDK which can be configured to fail silently,
+enterprise installs always fail loud on missing auth.
+
+## Framework instrumentation
+
+For automatic tracing of supported frameworks (Strands, etc.), install the OSS
+instrumentor package alongside this one:
+
+```bash
+pip install tracectrl-instrumentation-strands
+```
+
+The instrumentor hooks into the same global OpenTelemetry TracerProvider that
+`tracectrl-enterprise.configure()` sets up, so spans from instrumented
+framework calls are exported the same way as your `@tag_agent`-decorated
+functions.
+
+## License
+
+Apache 2.0. The TraceCtrl Enterprise server-side platform (engine, collector,
+UI) is BUSL-licensed; the SDK is permissively licensed so it can be
+embedded in your proprietary code without restriction.
+
+## Reporting issues
+
+https://github.com/tracectrl/tracectrl-enterprise/issues

tracectrl_enterprise-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tracectrl-enterprise"
+description = "TraceCtrl Enterprise SDK — agentic AI security observability for the enterprise platform"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "CloudsineAI" }]
+keywords = ["opentelemetry", "observability", "agents", "ai", "security"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "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",
+]
+dynamic = ["version"]
+
+# The OSS `tracectrl` core handles every piece of the OTel SDK plumbing —
+# TracerProvider, BatchSpanProcessor, OTLP exporter, attribute marshalling.
+# This package is a thin wrapper that adds the enterprise-specific bits:
+# required ingest-key auth, fail-loud defaults, and the `tag_agent()` API.
+#
+# Pin the OSS minor (>=0.3, <0.4) so semver-compatible bug fixes flow in
+# automatically but a future 0.4.0 with breaking changes can't silently
+# break customer installs. Bump the upper bound deliberately when we
+# qualify against a new OSS minor.
+dependencies = [
+    "tracectrl>=0.3,<0.4",
+]
+
+[project.optional-dependencies]
+# `dev` is for SDK contributors (us). Customers don't install this.
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.6",
+]
+
+[project.urls]
+Homepage = "https://tracectrl.ai"
+Repository = "https://github.com/tracectrl/tracectrl-enterprise"
+Documentation = "https://github.com/tracectrl/tracectrl-enterprise/blob/main/sdk/tracectrl-enterprise/README.md"
+
+[tool.hatch.version]
+path = "src/tracectrl_enterprise/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tracectrl_enterprise"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/tracectrl_enterprise/**",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tracectrl_enterprise-0.1.0/src/tracectrl_enterprise/__init__.py

@@ -0,0 +1,25 @@
+"""TraceCtrl Enterprise SDK — public API.
+
+Two exports that customers should use:
+
+    from tracectrl_enterprise import configure, tag_agent
+
+`configure()` initialises the OpenTelemetry pipeline against the enterprise
+collector with a required ingest key.
+
+`tag_agent()` is a decorator (and context manager) that wraps an agent
+function/block to emit a span with the canonical TraceCtrl attribute set —
+`openinference.span.kind=AGENT`, `tracectrl.agent.id`, etc. The collector's
+normalize processor relies on these being stamped at the source, not
+reconstructed from heuristics downstream.
+
+See README.md for a quickstart and the engine's span attribute contract
+(`docs/project/06-span-attribute-contract.md` in the source repo) for the
+full canonical attribute layout.
+"""
+
+from ._version import __version__
+from .api import tag_agent
+from .config import configure
+
+__all__ = ["configure", "tag_agent", "__version__"]

tracectrl_enterprise-0.1.0/src/tracectrl_enterprise/_version.py

@@ -0,0 +1,8 @@
+"""Single source of truth for the package version.
+
+Hatchling reads this at build time (see pyproject.toml `[tool.hatch.version]`)
+so the PyPI artifact, the importable `tracectrl_enterprise.__version__`, and
+git tags all stay in lockstep. Bump by editing this file and tagging.
+"""
+
+__version__ = "0.1.0"

tracectrl_enterprise-0.1.0/src/tracectrl_enterprise/api.py

@@ -0,0 +1,144 @@
+"""The ``tag_agent`` API — self-identifying agent spans.
+
+The TraceCtrl Enterprise pipeline relies on the SDK stamping canonical
+attributes at the source so the collector + worker never have to reconstruct
+agent identity from span-name heuristics (which is lossy and rename-fragile).
+See ``docs/project/06-span-attribute-contract.md`` in the source repo for the
+full attribute contract.
+
+This module exposes ``tag_agent`` as both a decorator and a context manager:
+
+    @tag_agent(id="payment-bot", name="PaymentAgent", framework="strands")
+    def run_agent(query: str) -> str:
+        ...
+
+    with tag_agent(id="payment-bot", name="PaymentAgent", framework="strands"):
+        # block-level usage
+        ...
+
+Both forms emit one span per invocation with the canonical TraceCtrl
+attribute set.
+"""
+
+from __future__ import annotations
+
+import functools
+from contextlib import contextmanager
+from typing import Any, Callable, Iterator
+
+from opentelemetry import trace
+
+# OpenInference span-kind values — the canonical ``openinference.span.kind``
+# attribute. ``AGENT`` is what every agent span carries; the rest are stamped
+# by other helpers (e.g. tool-call decorators we may add later) or by the
+# OSS framework instrumentors.
+SPAN_KIND_AGENT = "AGENT"
+
+
+def tag_agent(
+    *,
+    id: str,
+    name: str,
+    framework: str,
+    role: str | None = None,
+    session_id: str | None = None,
+):
+    """Mark a function or block as an agent invocation.
+
+    Stamps the canonical attribute set the TraceCtrl collector's normalize
+    processor expects:
+
+    * ``openinference.span.kind = "AGENT"``
+    * ``tracectrl.agent.id``      = ``id``
+    * ``tracectrl.agent.name``    = ``name``
+    * ``tracectrl.agent.framework`` = ``framework``
+    * ``tracectrl.agent.role``    = ``role`` (if given)
+    * ``tracectrl.session_id``    = ``session_id`` (if given)
+
+    Args:
+        id: Stable agent identifier (e.g. "payment-bot"). Used for inventory +
+            topology aggregation; must be deterministic across runs.
+        name: Human-readable name surfaced in the UI.
+        framework: Agent framework name (e.g. "strands", "agno", "langchain").
+        role: Optional free-form role/purpose label.
+        session_id: Optional session identifier for multi-turn grouping. Pass
+            the customer's own conversation/session id (e.g. a chat thread id)
+            to group all spans from that session together.
+
+    Returns:
+        A callable that's either a decorator (when used as ``@tag_agent(...)``)
+        or a context manager (when used in a ``with`` statement) — same
+        object, both protocols.
+    """
+    # Build the attribute dict once; the same span attributes apply to every
+    # invocation. Empty values are omitted so the collector's normalize
+    # processor doesn't see "" and treat it as a real value.
+    span_attrs: dict[str, Any] = {
+        "openinference.span.kind": SPAN_KIND_AGENT,
+        "tracectrl.agent.id": id,
+        "tracectrl.agent.name": name,
+        "tracectrl.agent.framework": framework,
+    }
+    if role:
+        span_attrs["tracectrl.agent.role"] = role
+    if session_id:
+        span_attrs["tracectrl.session_id"] = session_id
+
+    # The span name surfaces in the trace UI as the operation label. Use a
+    # deterministic format so it's easy to grep / group in the dashboard.
+    span_name = f"agent:{id}"
+
+    return _AgentTagger(span_name=span_name, attributes=span_attrs)
+
+
+class _AgentTagger:
+    """Dual decorator + context manager produced by ``tag_agent``.
+
+    Customers never instantiate this directly; ``tag_agent(...)`` returns it.
+    Implementing ``__call__`` enables the decorator syntax; ``__enter__`` /
+    ``__exit__`` enable the ``with`` syntax.
+    """
+
+    def __init__(self, span_name: str, attributes: dict[str, Any]) -> None:
+        self._span_name = span_name
+        self._attributes = attributes
+        self._cm: Iterator[trace.Span] | None = None
+
+    # --- decorator path -----------------------------------------------------
+
+    def __call__(self, fn: Callable[..., Any]) -> Callable[..., Any]:
+        """Decorator: wrap a callable so each call emits a tagged span."""
+
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            with _agent_span(self._span_name, self._attributes):
+                return fn(*args, **kwargs)
+
+        return wrapper
+
+    # --- context-manager path ----------------------------------------------
+
+    def __enter__(self) -> trace.Span:
+        self._cm = _agent_span(self._span_name, self._attributes)
+        return self._cm.__enter__()
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        assert self._cm is not None
+        self._cm.__exit__(exc_type, exc, tb)
+        self._cm = None
+
+
+@contextmanager
+def _agent_span(name: str, attrs: dict[str, Any]) -> Iterator[trace.Span]:
+    """Lowest-level helper: open a span with the canonical attrs, yield, close.
+
+    Uses the globally-installed TracerProvider set up by ``configure()``. If
+    ``configure()`` hasn't been called, the OTel SDK falls back to a no-op
+    provider — spans are still created but never exported. This matches the
+    OSS SDK's permissive default; the cost is only paid if the customer
+    forgets to call ``configure()`` (and they'd see no data in the dashboard,
+    which is its own loud signal).
+    """
+    tracer = trace.get_tracer("tracectrl_enterprise")
+    with tracer.start_as_current_span(name, attributes=attrs) as span:
+        yield span

tracectrl_enterprise-0.1.0/src/tracectrl_enterprise/config.py

@@ -0,0 +1,78 @@
+"""Enterprise configuration entry point.
+
+Thin wrapper over OSS ``tracectrl.configure()`` that adds the enterprise
+defaults and policies the customer-facing surface depends on:
+
+* **required ingest key** — unauthenticated traffic never reaches the
+  enterprise collector (it rejects at the trust boundary). Calling
+  ``configure()`` without an ingest key raises ``ValueError`` immediately
+  rather than silently exporting spans the collector will reject.
+* **enterprise endpoint default** — ``https://app.tracectrl.ai/ingest``
+  rather than localhost; overridable for staging or self-hosted deploys.
+* **fail-loud** — OSS supports ``fail_silently=True`` for dev convenience;
+  enterprise sets ``False`` so misconfiguration surfaces during local
+  testing, not in production.
+
+The OSS package does everything else: TracerProvider setup, BatchSpanProcessor,
+OTLP exporter, resource attributes. We import its ``configure`` and delegate.
+"""
+
+from __future__ import annotations
+
+import os
+
+from tracectrl import configure as _oss_configure  # type: ignore[import-untyped]
+
+# Production collector — the nginx /ingest/ route on the SaaS deploy. Override
+# via VITE-style env var or the `endpoint=` arg for staging / self-hosted.
+DEFAULT_ENDPOINT = "https://app.tracectrl.ai/ingest"
+DEFAULT_SERVICE_NAME = "tracectrl-agent"
+
+
+def configure(
+    *,
+    ingest_key: str | None = None,
+    endpoint: str | None = None,
+    service_name: str | None = None,
+) -> None:
+    """Initialise the OpenTelemetry pipeline against TraceCtrl Enterprise.
+
+    Call once at application startup, before any instrumented code runs.
+
+    Args:
+        ingest_key: The customer's ingest key from the TraceCtrl admin console.
+            Reads ``TRACECTRL_INGEST_KEY`` from env if not given. Required;
+            raises ``ValueError`` if neither argument nor env is set.
+        endpoint: The OTLP/gRPC collector endpoint. Defaults to
+            ``https://app.tracectrl.ai/ingest``. Override via this argument or
+            ``TRACECTRL_ENDPOINT`` env var for staging / self-hosted.
+        service_name: ``service.name`` resource attribute, surfaces in the
+            ``ServiceName`` column. Defaults to ``tracectrl-agent``; override via
+            this argument or ``TRACECTRL_SERVICE_NAME`` env var.
+
+    Raises:
+        ValueError: if no ingest key is provided.
+    """
+    key = ingest_key or os.getenv("TRACECTRL_INGEST_KEY")
+    if not key:
+        raise ValueError(
+            "tracectrl-enterprise requires an ingest key. "
+            "Pass ingest_key=... or set TRACECTRL_INGEST_KEY in the environment. "
+            "Get one from your TraceCtrl admin console."
+        )
+
+    resolved_endpoint = endpoint or os.getenv("TRACECTRL_ENDPOINT") or DEFAULT_ENDPOINT
+    resolved_service = (
+        service_name or os.getenv("TRACECTRL_SERVICE_NAME") or DEFAULT_SERVICE_NAME
+    )
+
+    # Delegate to OSS — it handles TracerProvider, BatchSpanProcessor, OTLP
+    # exporter wiring. The `api_key` arg becomes the `Authorization: Bearer`
+    # header on every OTLP export (OSS reads it and sets the exporter's
+    # gRPC metadata).
+    _oss_configure(
+        endpoint=resolved_endpoint,
+        service_name=resolved_service,
+        api_key=key,
+        fail_silently=False,
+    )