o11y-one 0.1.0__tar.gz

o11y_one-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Build artifacts. Note what is NOT here: packages/*/src/o11y_one and
+# gen/go/o11y_one are GENERATED but COMMITTED on purpose — see README, "The
+# regen ritual". Only compiler output is ignored.
+node_modules/
+dist/
+*.tsbuildinfo
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+
+# Go
+/tools/ci-runner/bin/
+/tools/pr-diff/bin/
+/dist-bin/
+
+# mise/local
+.mise.local.toml
+
+# OS
+.DS_Store

o11y_one-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.5
+Name: o11y-one
+Version: 0.1.0
+Summary: Hand-written Python client for the O11y One API: transport construction, credential injection, and the O11y One error taxonomy.
+Project-URL: Homepage, https://o11y.one
+Project-URL: Source, https://github.com/o11y-one/o11y-one-sdk
+Author: O11y One
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: connect-python<1,>=0.9.0
+Requires-Dist: httpx>=0.28
+Requires-Dist: o11y-one-api-agentic
+Description-Content-Type: text/markdown
+
+# `o11y-one`
+
+The Python client for the O11y One API. A thin, hand-written layer over the
+generated [`o11y-one-api-agentic`](../gen-py-agentic) package.
+
+## Install
+
+```sh
+uv add o11y-one        # or: pip install o11y-one
+```
+
+## Use
+
+```python
+import os
+
+from o11y_one.sdk import O11yClient, Disposition, classify
+from o11y_one.agentic.v1.evaluation_pb2 import ListEvaluationDefinitionsRequest
+from o11y_one.agentic.v1.evaluation_connect import AgenticEvaluationServiceClientSync
+
+o11y = O11yClient(
+    base_url="https://api.o11y.one",
+    credential=os.environ["O11Y_API_KEY"],  # o11y_mach.<selector>.<secret>
+    org_id=os.environ["O11Y_ORG_ID"],
+)
+
+evals = o11y.service_sync(AgenticEvaluationServiceClientSync)
+try:
+    defs = evals.list_evaluation_definitions(ListEvaluationDefinitionsRequest())
+except Exception as err:  # noqa: BLE001 - classify sorts it out
+    failure = classify(err)
+    if failure.disposition is Disposition.INSUFFICIENT_SCOPE:
+        raise SystemExit(f"credential is missing scope {failure.missing_scope}") from err
+    raise
+```
+
+## What is here, and what deliberately is not
+
+Three modules and nothing else:
+
+| module | responsibility |
+|---|---|
+| `o11y_one.sdk.client` | transport construction, credential and scoping header injection |
+| `o11y_one.sdk.auth`   | the credential wire format and local structural validation |
+| `o11y_one.sdk.errors` | the failure taxonomy: reauthenticate / insufficient-scope / version-skew / retry / unclassified |
+
+Service methods are **not** wrapped. `o11y-one-api-agentic` already ships a client class
+per service; a hand-written facade over all of them would be a second API surface
+to keep in sync with the proto, and it would rot the first time a field is added
+upstream. Import the generated client class and hand it to
+`O11yClient.service_sync()` / `O11yClient.service()`.
+
+## The distinction this package exists to preserve
+
+`UNAUTHENTICATED` and `PERMISSION_DENIED` are different problems:
+
+* **`UNAUTHENTICATED`** — the credential is absent, malformed, unknown, expired,
+  or revoked. Re-auth. Retrying cannot change the answer.
+* **`PERMISSION_DENIED`** — the credential is fine; it lacks a scope (the server
+  names which one) or it was presented to a non-machine surface.
+
+`classify()` keeps them apart, along with `UNAVAILABLE` (auth backend down —
+retry with backoff) and `INVALID_ARGUMENT` (SDK/server version skew). Collapsing
+these into a single "auth error" is the failure mode this module exists to
+prevent.
+
+## Credentials
+
+A machine credential is `o11y_mach.<selector>.<secret>`, presented in the
+`x-o11y-key` header. It is:
+
+* **returned exactly once**, by `CreateMachineCredential`. There is no read-back
+  RPC and no recovery path — lose it and you rotate.
+* **rotated create-then-revoke**, not atomically. A principal may hold several
+  active credentials at once, which is what makes zero-downtime rotation work:
+  create the new one, deploy it, then revoke the old.
+* **revoked effective on the next request**, not on a TTL boundary.
+* **expiring** at +365 days by default, capped at three years.
+
+Never send it as `authorization: Bearer` — that path carries the browser session
+JWT and a machine credential presented there is rejected.

o11y_one-0.1.0/README.md

@@ -0,0 +1,81 @@
+# `o11y-one`
+
+The Python client for the O11y One API. A thin, hand-written layer over the
+generated [`o11y-one-api-agentic`](../gen-py-agentic) package.
+
+## Install
+
+```sh
+uv add o11y-one        # or: pip install o11y-one
+```
+
+## Use
+
+```python
+import os
+
+from o11y_one.sdk import O11yClient, Disposition, classify
+from o11y_one.agentic.v1.evaluation_pb2 import ListEvaluationDefinitionsRequest
+from o11y_one.agentic.v1.evaluation_connect import AgenticEvaluationServiceClientSync
+
+o11y = O11yClient(
+    base_url="https://api.o11y.one",
+    credential=os.environ["O11Y_API_KEY"],  # o11y_mach.<selector>.<secret>
+    org_id=os.environ["O11Y_ORG_ID"],
+)
+
+evals = o11y.service_sync(AgenticEvaluationServiceClientSync)
+try:
+    defs = evals.list_evaluation_definitions(ListEvaluationDefinitionsRequest())
+except Exception as err:  # noqa: BLE001 - classify sorts it out
+    failure = classify(err)
+    if failure.disposition is Disposition.INSUFFICIENT_SCOPE:
+        raise SystemExit(f"credential is missing scope {failure.missing_scope}") from err
+    raise
+```
+
+## What is here, and what deliberately is not
+
+Three modules and nothing else:
+
+| module | responsibility |
+|---|---|
+| `o11y_one.sdk.client` | transport construction, credential and scoping header injection |
+| `o11y_one.sdk.auth`   | the credential wire format and local structural validation |
+| `o11y_one.sdk.errors` | the failure taxonomy: reauthenticate / insufficient-scope / version-skew / retry / unclassified |
+
+Service methods are **not** wrapped. `o11y-one-api-agentic` already ships a client class
+per service; a hand-written facade over all of them would be a second API surface
+to keep in sync with the proto, and it would rot the first time a field is added
+upstream. Import the generated client class and hand it to
+`O11yClient.service_sync()` / `O11yClient.service()`.
+
+## The distinction this package exists to preserve
+
+`UNAUTHENTICATED` and `PERMISSION_DENIED` are different problems:
+
+* **`UNAUTHENTICATED`** — the credential is absent, malformed, unknown, expired,
+  or revoked. Re-auth. Retrying cannot change the answer.
+* **`PERMISSION_DENIED`** — the credential is fine; it lacks a scope (the server
+  names which one) or it was presented to a non-machine surface.
+
+`classify()` keeps them apart, along with `UNAVAILABLE` (auth backend down —
+retry with backoff) and `INVALID_ARGUMENT` (SDK/server version skew). Collapsing
+these into a single "auth error" is the failure mode this module exists to
+prevent.
+
+## Credentials
+
+A machine credential is `o11y_mach.<selector>.<secret>`, presented in the
+`x-o11y-key` header. It is:
+
+* **returned exactly once**, by `CreateMachineCredential`. There is no read-back
+  RPC and no recovery path — lose it and you rotate.
+* **rotated create-then-revoke**, not atomically. A principal may hold several
+  active credentials at once, which is what makes zero-downtime rotation work:
+  create the new one, deploy it, then revoke the old.
+* **revoked effective on the next request**, not on a TTL boundary.
+* **expiring** at +365 days by default, capped at three years.
+
+Never send it as `authorization: Bearer` — that path carries the browser session
+JWT and a machine credential presented there is rejected.

o11y_one-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "o11y-one"
+version = "0.1.0"
+description = "Hand-written Python client for the O11y One API: transport construction, credential injection, and the O11y One error taxonomy."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+authors = [{ name = "O11y One" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+]
+
+dependencies = [
+  "o11y-one-api-agentic",
+  "connect-python>=0.9.0,<1",
+  "httpx>=0.28",
+]
+
+[project.urls]
+Homepage = "https://o11y.one"
+Source = "https://github.com/o11y-one/o11y-one-sdk"
+
+[build-system]
+requires = ["hatchling>=1.32.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+# o11y_one is a PEP 420 namespace shared with o11y-one-api-agentic; this
+# distribution owns exactly o11y_one/sdk. No src/o11y_one/__init__.py, ever —
+# adding one would shadow the generated o11y_one.agentic, o11y_one.common
+# packages.
+packages = ["src/o11y_one"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md", "pyproject.toml"]
+
+[tool.uv.sources]
+# Inside the workspace, resolve the generated package from the sibling member
+# rather than PyPI, so the SDK always builds against the generated code from
+# THIS commit. Published wheels carry the plain `o11y-one-api-agentic`
+# requirement. The agentic SDK depends on the per-domain subset distribution
+# (agentic + common only), not the whole o11y-one-api — see
+# docs/proto-subsetting.md.
+o11y-one-api-agentic = { workspace = true }
+
+[dependency-groups]
+dev = ["pytest>=8.4"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

o11y_one-0.1.0/src/o11y_one/sdk/__init__.py

@@ -0,0 +1,82 @@
+"""``o11y_one.sdk`` — hand-written client layer over the generated ``o11y_one.*``
+protobuf packages shipped by the ``o11y-one-api`` distribution.
+
+Four things live here:
+
+* transport construction (:mod:`o11y_one.sdk.client`)
+* credential injection and its local validation (:mod:`o11y_one.sdk.auth`)
+* the failure taxonomy an SDK exists to render (:mod:`o11y_one.sdk.errors`)
+* an ergonomic facade over exactly ONE generated service,
+  ``AgenticEvaluationService`` (:mod:`o11y_one.sdk.agentic`)
+
+For every other generated service, methods are still NOT wrapped or
+re-exported: import the generated ``*ServiceClient`` you need from
+``o11y_one.<domain>.v1.<file>_connect`` and hand the class to
+:meth:`O11yClient.service` / :meth:`O11yClient.service_sync`. The rationale for
+staying thin there is unchanged — a hand-written facade over every one of the
+29 generated services would be a second API surface to keep in sync with the
+proto, and it would rot the first time a field is added upstream.
+
+``AgenticEvaluationService`` is the deliberate exception, not a reversal of
+that rule: it is the run-submission / lease-heartbeat-submit-release /
+dataset-draft / annotation surface an eval-authoring or externally-executed
+runtime integration calls minute to minute, its messages repeat the same
+refusal-on-a-200, idempotency and capability-envelope conventions across
+dozens of RPCs, and getting any one of those conventions wrong locally
+degrades silently to an opaque network error rather than a loud local one. See
+:mod:`o11y_one.sdk.agentic` for what the facade adds on top of the generated
+client, and ``l2-notes.md`` for why this scope was drawn where it was.
+
+Note that ``o11y_one`` itself is a PEP 420 namespace package contributed to by
+two distributions: ``o11y-one-api`` (generated) and ``o11y-one`` (this one).
+There is deliberately no ``o11y_one/__init__.py`` in either.
+"""
+
+from __future__ import annotations
+
+from .agentic import (
+    MACHINE_SCOPE_NAME_TO_ENUM,
+    AgenticClient,
+    AgenticClientSync,
+    CaseOutput,
+    IssuedMachineCredential,
+)
+from .auth import (
+    CREDENTIAL_HEADER,
+    CREDENTIAL_MAX_LEN,
+    MACHINE_CREDENTIAL_PREFIX,
+    ORG_ID_HEADER,
+    TENANT_ID_HEADER,
+    assert_looks_like_machine_credential,
+)
+from .client import CredentialInterceptor, O11yClient
+from .errors import MACHINE_SCOPES, ClassifiedFailure, Disposition, classify
+from .recovery import bare_enum_name, find_error_detail
+from .results import Refusal
+from .validation import ValidationError
+
+__all__ = [
+    "CREDENTIAL_HEADER",
+    "CREDENTIAL_MAX_LEN",
+    "MACHINE_CREDENTIAL_PREFIX",
+    "MACHINE_SCOPES",
+    "MACHINE_SCOPE_NAME_TO_ENUM",
+    "ORG_ID_HEADER",
+    "TENANT_ID_HEADER",
+    "AgenticClient",
+    "AgenticClientSync",
+    "CaseOutput",
+    "ClassifiedFailure",
+    "CredentialInterceptor",
+    "Disposition",
+    "IssuedMachineCredential",
+    "O11yClient",
+    "Refusal",
+    "ValidationError",
+    "assert_looks_like_machine_credential",
+    "bare_enum_name",
+    "classify",
+    "find_error_detail",
+]
+
+__version__ = "0.0.0"