coding-sh 0.1.3__py3-none-any.whl

coding_sh/otel.py

@@ -0,0 +1,144 @@
+"""OpenTelemetry gen_ai setup for coding.sh, for apps that already emit OTel spans.
+
+coding.sh serve takes OTLP/HTTP at <url>/v1/traces, so plain OTel works with four env vars
+(docs/PRODUCTION.md section 4.3). This module only saves the boilerplate:
+
+    from coding_sh.otel import configure
+    configure(service="checkout-api")   # TracerProvider + OTLP/HTTP exporter + Bearer key
+
+    # or, for a subprocess / `opentelemetry-instrument`:
+    env = {**os.environ, **coding_sh.otel.otel_env()}
+
+configure() resolves the endpoint like this: explicit `url`, then the standard
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT / OTEL_EXPORTER_OTLP_ENDPOINT (left to the exporter, with
+OTEL_EXPORTER_OTLP_HEADERS), then CODING_SH_URL + CODING_SH_INGEST_KEY. It also stamps
+`gen_ai.conversation.id` on spans started inside coding_sh.with_session(...) or
+coding_sh.trace(session_id=...), so OTel spans group into the same conversation session.
+
+Needs `pip install coding-sh[otel]` (opentelemetry-sdk, opentelemetry-exporter-otlp-proto-http).
+Without them, configure() warns once and returns None; it never raises into the app.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import urllib.parse
+from typing import Any, Dict, Optional
+
+from ._trace import current_session_id
+
+log = logging.getLogger("coding_sh")
+
+CONVERSATION_ATTR = "gen_ai.conversation.id"
+
+
+def _env(name: str) -> Optional[str]:
+    v = os.environ.get(name)
+    return v if v else None
+
+
+def otel_env(url: Optional[str] = None, key: Optional[str] = None, service: Optional[str] = None) -> Dict[str, str]:
+    """OTEL_* exporter env vars that point any OTel SDK at a coding.sh server.
+
+    Defaults come from CODING_SH_URL, CODING_SH_INGEST_KEY and CODING_SH_SERVICE. The result
+    holds the ingest key: pass it to a child process, never log it.
+    """
+    url = url or _env("CODING_SH_URL")
+    key = key or _env("CODING_SH_INGEST_KEY")
+    service = service or _env("CODING_SH_SERVICE") or _env("OTEL_SERVICE_NAME")
+    env: Dict[str, str] = {}
+    if url:
+        env["OTEL_EXPORTER_OTLP_ENDPOINT"] = url.rstrip("/")
+        env["OTEL_EXPORTER_OTLP_PROTOCOL"] = "http/protobuf"
+    if key:
+        env["OTEL_EXPORTER_OTLP_HEADERS"] = "Authorization=" + urllib.parse.quote("Bearer " + key)
+    if service:
+        env["OTEL_SERVICE_NAME"] = service
+    return env
+
+
+class ConversationSpanProcessor:
+    """Sets gen_ai.conversation.id from the current coding.sh session on every new span."""
+
+    def on_start(self, span: Any, parent_context: Any = None) -> None:
+        try:
+            sid = current_session_id()
+            if not sid:
+                return
+            attrs = getattr(span, "attributes", None) or {}
+            if CONVERSATION_ATTR not in attrs and "session.id" not in attrs:
+                span.set_attribute(CONVERSATION_ATTR, sid)
+        except Exception:
+            pass
+
+    def on_end(self, span: Any) -> None:
+        pass
+
+    def _on_ending(self, span: Any) -> None:  # newer SDKs call this hook
+        pass
+
+    def shutdown(self) -> None:
+        pass
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        return True
+
+
+_warned = False
+
+
+def configure(
+    service: Optional[str] = None,
+    url: Optional[str] = None,
+    key: Optional[str] = None,
+    set_global: bool = True,
+    batch: bool = True,
+) -> Any:
+    """Build (and by default install) a TracerProvider that exports to coding.sh.
+
+    Returns the provider, or None when OpenTelemetry is not installed or no endpoint is known.
+    Call provider.shutdown() (or rely on the SDK's atexit hook) to flush on exit.
+    """
+    global _warned
+    try:
+        from opentelemetry import trace as otel_trace
+        from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+        from opentelemetry.sdk.resources import Resource
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor, SimpleSpanProcessor
+    except Exception:
+        if not _warned:
+            _warned = True
+            log.warning("coding.sh: OpenTelemetry is not installed; pip install 'coding-sh[otel]'")
+        return None
+    try:
+        exporter_kwargs: Dict[str, Any] = {}
+        has_otel_endpoint = bool(_env("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT") or _env("OTEL_EXPORTER_OTLP_ENDPOINT"))
+        base = url or (None if has_otel_endpoint else _env("CODING_SH_URL"))
+        if base:
+            base = base.rstrip("/")
+            exporter_kwargs["endpoint"] = base if base.endswith("/v1/traces") else base + "/v1/traces"
+        elif not has_otel_endpoint:
+            if not _warned:
+                _warned = True
+                log.warning("coding.sh: no endpoint; set CODING_SH_URL or OTEL_EXPORTER_OTLP_ENDPOINT")
+            return None
+        k = key or (None if (has_otel_endpoint and not url) else _env("CODING_SH_INGEST_KEY"))
+        if k:
+            exporter_kwargs["headers"] = {"Authorization": "Bearer " + k}
+        name = service or _env("OTEL_SERVICE_NAME") or _env("CODING_SH_SERVICE")
+        resource = Resource.create({"service.name": name} if name else {})
+        provider = TracerProvider(resource=resource)
+        provider.add_span_processor(ConversationSpanProcessor())  # type: ignore[arg-type]
+        exporter = OTLPSpanExporter(**exporter_kwargs)
+        provider.add_span_processor(BatchSpanProcessor(exporter) if batch else SimpleSpanProcessor(exporter))
+        if set_global:
+            otel_trace.set_tracer_provider(provider)
+        return provider
+    except Exception as e:
+        log.warning("coding.sh: OpenTelemetry setup failed: %s", type(e).__name__)
+        return None
+
+
+__all__ = ["configure", "otel_env", "ConversationSpanProcessor", "CONVERSATION_ATTR"]

coding_sh-0.1.3.dist-info/METADATA

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: coding-sh
+Version: 0.1.3
+Summary: Trace any AI agent or LLM app from Python: send model calls, traces and tool spans to a coding.sh server.
+Author: coding.sh contributors
+License-Expression: MIT
+Project-URL: Homepage, https://coding.sh
+Project-URL: Repository, https://github.com/jackulau/coding.sh
+Project-URL: Source, https://github.com/jackulau/coding.sh/tree/main/packages/sdk-python
+Project-URL: Issues, https://github.com/jackulau/coding.sh/issues
+Project-URL: Changelog, https://github.com/jackulau/coding.sh/blob/main/CHANGELOG.md
+Keywords: ai agents,observability,evals,opentelemetry,llm,claude code,codex,openai,anthropic,tracing
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30; extra == "anthropic"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-sdk>=1.20; extra == "otel"
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20; extra == "otel"
+Dynamic: license-file
+
+# coding-sh (Python SDK)
+
+Send LLM calls, traces and tool spans from any Python service to a
+[coding.sh](https://coding.sh) server (`coding.sh serve`). Stdlib only, Python 3.9+.
+
+```sh
+pip install coding-sh
+export CODING_SH_URL=https://obs.example.com CODING_SH_INGEST_KEY=csh_ik_...
+```
+
+```python
+import coding_sh
+from openai import OpenAI
+
+client = coding_sh.observe(OpenAI())   # also AsyncOpenAI, Anthropic, AsyncAnthropic
+```
+
+That's it: every `chat.completions.create`, `responses.create` and `messages.create` /
+`messages.stream` call (sync, async and streaming) becomes an `llm.call` with tokens, model,
+latency, time to first token, stop reason and tool calls. The server prices it.
+
+Without `CODING_SH_URL` the SDK does nothing. It never changes return values, errors or stream
+semantics, and never raises into your app.
+
+## Traces, tools and conversations
+
+```python
+with coding_sh.trace("support-reply", session_id=conversation_id, user_id=user.id, input=question) as t:
+    with coding_sh.span("tool", "lookup_order", input={"id": 42}) as s:
+        s.set_output(orders.get(42))
+    reply = client.chat.completions.create(model="gpt-4o-mini", messages=msgs)
+    t.set_output(reply.choices[0].message.content)
+```
+
+- Each top-level `trace()` (or untraced call) is its own session. Pass `session_id` (or wrap code
+  in `coding_sh.with_session(id)`) to make each trace a turn of one conversation.
+- `trace` and `span` are context managers (`with` / `async with`) and decorators. A decorated
+  `span("tool", ...)` records the call's arguments as input and its return value as output.
+- `span("step", name)` records a generic step.
+- Context follows `contextvars`, so it crosses `await` and asyncio tasks. Work handed to a thread
+  pool starts untraced unless you run it with `contextvars.copy_context().run`.
+
+## LLM gateways
+
+Point the client at a gateway and each call records which one it went through, and the request id
+the gateway's lookup API takes, so `coding.sh gateway enrich` can add the billed cost and
+`coding.sh sessions --flag gateway:<name>` finds the sessions. Detected: Vercel AI Gateway,
+OpenRouter, LiteLLM, Cloudflare AI Gateway, Portkey, Helicone, Requesty, Ramp Router (router.com),
+TrueFoundry, Kong, Bifrost and Martian, by base URL (a self-hosted gateway by its URL env var, e.g.
+`LITELLM_PROXY_API_BASE`), by response header (`cf-aig-log-id`, `helicone-id`, `x-litellm-call-id`,
+`x-portkey-trace-id`, …) or by response id (`gen_…`, `gen-…`, `rqsty-…`).
+`observe()` adds a response hook to the client's HTTP client that reads headers only, and only for
+calls it records. [Details](https://github.com/jackulau/coding.sh/blob/main/docs/integrations/ai-gateway.md#from-the-sdks).
+
+```python
+client = coding_sh.observe(OpenAI(base_url="https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/compat"))
+```
+
+## Delivery
+
+One daemon thread sends batches (up to 500 events or 4 MiB, gzip) to `POST /v1/ingest`. It retries
+429, 5xx and network errors (honoring `Retry-After`, else 1, 2, 4 ... s, at most 5 attempts) with
+stable event ids, so retries never duplicate. 400/401/403 drop the batch with one warning. A full
+queue drops new events and counts them. An `atexit` flush is bounded to 2 s.
+
+```python
+coding_sh.flush(timeout=5)     # e.g. at the end of a script, a job or a serverless handler
+coding_sh.shutdown()           # flush, then stop
+coding_sh.stats()              # {"queued", "sent", "dropped", "failed"}
+```
+
+## Config
+
+`coding_sh.init(url=, key=, service=, capture=, flush_interval_ms=1000, max_batch=500, max_queue=10000, disabled=, debug=)`
+is optional; arguments override env vars.
+
+| Env | Meaning |
+|---|---|
+| `CODING_SH_URL` | Server base URL. Unset = SDK off. |
+| `CODING_SH_INGEST_KEY` | `csh_ik_...` ingest key. It decides the project. |
+| `CODING_SH_SERVICE` (or `OTEL_SERVICE_NAME`) | Service name; becomes the session's agent id. |
+| `CODING_SH_CAPTURE_MODE` | `full` (default) or `metadata` (no message text or tool I/O). |
+| `CODING_SH_DISABLED=1` | Turn the SDK off. |
+| `CODING_SH_DEBUG=1` | Log transport details (never keys or bodies). |
+
+## OpenTelemetry
+
+Already emitting gen_ai spans? Point OTel at the server instead (no SDK needed), or let the
+helper do the setup:
+
+```python
+from coding_sh.otel import configure, otel_env
+configure(service="checkout-api")   # TracerProvider + OTLP/HTTP exporter + Bearer key
+env = otel_env()                    # OTEL_EXPORTER_OTLP_* vars for a subprocess
+```
+
+`pip install 'coding-sh[otel]'`. `configure()` uses the standard `OTEL_EXPORTER_OTLP_*` env vars
+when set, else `CODING_SH_URL` / `CODING_SH_INGEST_KEY`, and stamps `gen_ai.conversation.id` from
+the current `with_session` / `trace(session_id=...)`.
+
+## Tests
+
+```sh
+python3 -m unittest discover -s tests -t tests
+```
+
+The provider tests use fake clients and always run. Tests against the real `openai`, `anthropic`
+and OpenTelemetry packages run when those are installed.

coding_sh-0.1.3.dist-info/RECORD

@@ -0,0 +1,14 @@
+coding_sh/__init__.py,sha256=dtZ9V6DB_5J7MSuH3WE-1ZsW3RxZ9t-YWMeKgD3jNlM,1107
+coding_sh/_client.py,sha256=xlyxT7ynsXs7SEdCOGwN0ljr1uvRJcSaYU3-emCO5YM,15877
+coding_sh/_gateway.py,sha256=uzSNl9C-9n0q3M6V51owLScK0wQcB8kh2qrv2-JDjQ8,5401
+coding_sh/_gateway_table.py,sha256=NeohPsRPgNhl7EBPy3u39eb5-mvbOPQ3JQbLfoMy-xk,3516
+coding_sh/_llm.py,sha256=pOwT5YTA7dyJ_dAGptICy8vQVlhPvF9hp76pqMXEDwQ,11003
+coding_sh/_providers.py,sha256=Kz2tXqctbysTt3eZpd5ws1wXE1DoIhE74gCodeKlB_g,19195
+coding_sh/_trace.py,sha256=OdSOn_IiX_EsaItF1W_MKRVaE3-qy2d80f6icqeILBs,21979
+coding_sh/otel.py,sha256=_eq1E6ae5Yk-OGwja9f187y2BkUeFg_uV8R5Vp5SrJk,5773
+coding_sh/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+coding_sh-0.1.3.dist-info/licenses/LICENSE,sha256=uDSs7rzgBZqwq0KlOzhLZnBPeBfTcGI8ijcPbxQ2tHc,1079
+coding_sh-0.1.3.dist-info/METADATA,sha256=ZFS0kS9YNrILVv8X_mgOhRqQAlU3sVM4NMYmBBj8erk,6318
+coding_sh-0.1.3.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+coding_sh-0.1.3.dist-info/top_level.txt,sha256=rbbP9kA9i8EteSHOy7U6-bB9AQetzeu17i-Gluy684U,10
+coding_sh-0.1.3.dist-info/RECORD,,

coding_sh-0.1.3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

coding_sh-0.1.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 coding.sh contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

coding_sh-0.1.3.dist-info/top_level.txt

@@ -0,0 +1 @@
+coding_sh