uncoil-sdk 0.6.0__tar.gz

uncoil_sdk-0.6.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: uncoil-sdk
+Version: 0.6.0
+Summary: Observability, runtime enforcement, and tracing for AI agents.
+Author-email: Uncoil Team <hello@uncoil.dev>
+License-Expression: MIT
+Project-URL: Homepage, https://www.uncoil.dev
+Project-URL: Documentation, https://www.uncoil.dev/docs
+Project-URL: Bug Tracker, https://github.com/Uncoil-dev/Uncoil/issues
+Project-URL: Source, https://github.com/Uncoil-dev/Uncoil
+Keywords: ai,agents,observability,tracing,llm,llm-observability,agent-tracing,opentelemetry,cost-tracking,langchain,openai,anthropic
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.25; extra == "anthropic"
+Provides-Extra: langgraph
+Requires-Dist: langchain-core>=0.2; extra == "langgraph"
+Requires-Dist: langgraph>=0.2; extra == "langgraph"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-asyncio>=0.24; extra == "test"
+Requires-Dist: httpx2==2.13.1; extra == "test"
+Requires-Dist: openai==3.31.0; extra == "test"
+Requires-Dist: anthropic==1.14.0; extra == "test"
+Requires-Dist: langgraph==1.2.15; extra == "test"
+Requires-Dist: langchain-core==1.6.10; extra == "test"
+
+# Uncoil Python SDK
+
+Observability and tracing for AI agents. Gain full visibility into your agent's decision-making process, tool usage, and LLM costs.
+
+Uncoil records each agent run as one trace: every model call, tool call, retry, failure and cost. It also ingests OpenTelemetry. Free plan available. Docs: [uncoil.dev/docs](https://www.uncoil.dev/docs). New to agent observability? Read the [complete guide](https://www.uncoil.dev/blog/ai-agent-observability-complete-guide).
+
+## Installation
+
+```bash
+pip install uncoil-sdk
+```
+
+## Quickstart
+
+1. Get your API Key from the [Uncoil Dashboard](https://www.uncoil.dev).
+2. Set it as an environment variable:
+
+```bash
+export UNCOIL_API_KEY=your_sk_live_...
+```
+
+3. Instrument your agent:
+
+```python
+from uncoil import trace_agent, llm_call, tool_call
+
+@trace_agent(environment="development", release="quickstart")
+async def my_agent(query: str):
+    # LLM Call
+    llm_call(
+        input_data=query,
+        output_data="Thinking...",
+        model_id="gpt-4o",
+        cost_usd=0.002,
+        latency_ms=800
+    )
+    
+    # Tool Use
+    tool_call(
+        tool_name="web_search",
+        input_data={"q": query},
+        output_data="Found results...",
+        latency_ms=1200
+    )
+    
+    return "Final Answer"
+```
+
+## Steps
+
+Inside a `@trace_agent` function, every step you record is linked to the step it ran in, so the trace graph
+shows which step called which and how loops repeat. Use `span` for a block and `observe` for a function:
+
+```python
+import uncoil
+
+@uncoil.observe(type="tool")
+def search_docs(query):
+    return search(query)
+
+@uncoil.trace_agent()
+def answer(question):
+    for turn in range(5):
+        with uncoil.span("think", type="agent"):
+            with uncoil.span("chat", type="llm", input=question) as step:
+                reply = call_model(question)
+                step.set_output(reply.text)
+                step.set(model="claude-sonnet-5-5", input_tokens=reply.usage.input, output_tokens=reply.usage.output)
+            if reply.done:
+                return reply.text
+            search_docs(reply.query)
+```
+
+`type` is one of `agent`, `llm`, `tool`, `retrieval` or `span`. Errors are recorded with their type and
+message. Concurrent runs (threads or asyncio tasks) stay in separate traces. Inputs and outputs have obvious
+secrets (bearer tokens, API keys, JWTs, `password=` values) removed and are capped at 10,000 characters;
+avoid sending anything else you would not want stored.
+
+## Features
+
+- **@trace_agent Decorator:** Automatically captures run lifecycle and errors.
+- **Granular Spans:** Manually record LLMs, tools, and custom decisions.
+- **Cost Tracking:** Monitor your infrastructure spend in real-time.
+- **Asynchronous & Synchronous Support:** Works with `async/await` or standard functions.
+- **Session context:** Attach `session_id`, `end_user_id`, `environment`, `release`, and `tags` to connect related traces.
+
+## Feedback and evaluation scores
+
+Pass `project_id` when constructing the client to attach end-user feedback and typed scores to traces:
+
+```python
+client = UncoilClient(project_id="your-project-id")
+client.feedback(run_id, True, kind="thumb", comment="Helpful answer")
+client.score(run_id, "answer_quality", 0.92, data_type="numeric")
+```
+
+Feedback and scores use the same API key as ingestion and do not interrupt the agent when delivery fails.
+
+## Prompt deployment
+
+Resolve a deployed prompt without shipping a new application build:
+
+```python
+deployed = client.get_prompt("support-agent", "production")
+client.ingest(spanType="llm", input=question, output=answer, promptVersionId=deployed["version"]["id"])
+```
+
+Prompt responses are cached for 60 seconds by default. Use `cache_ttl_seconds=0` or provide a `fallback` for development and guaranteed-availability behavior.
+
+## License
+
+MIT
+
+## Provider integrations (0.4.0)
+
+Install the optional provider/framework extras you use: `pip install 'uncoil-sdk[openai,anthropic,langgraph]'`.
+Set `UNCOIL_API_KEY` and the existing regional configuration.
+
+```python
+import uncoil
+from openai import OpenAI, AsyncOpenAI
+from anthropic import Anthropic
+
+openai = uncoil.wrap_openai(OpenAI())
+anthropic = uncoil.wrap_anthropic(Anthropic())
+async_openai = uncoil.wrap_openai(AsyncOpenAI())
+# Existing create calls keep their provider response types and exceptions.
+reply = openai.responses.create(model=MODEL, input="Hello")
+with anthropic.messages.stream(model=MODEL, max_tokens=100,
+        messages=[{"role": "user", "content": "Hello"}]) as stream:
+    for text in stream.text_stream:
+        print(text, end="")
+
+# Add a callback to a compiled LangGraph invocation.
+graph.invoke(inputs, config={"callbacks": [uncoil.langgraph_callback()]})
+```
+
+Wrap sync or async clients once. Supported: OpenAI chat completions and Responses `create` APIs,
+including streams; Anthropic messages `create`/`stream` and beta equivalents, including sync/async
+context managers, text streams and final messages. Close streams when stopping early. Raw response
+resources and unsupported convenience methods are passed through without instrumentation.
+
+Calls inside `trace_agent`/`span` inherit their run/parent and custom client. Standalone calls receive
+an independent completed root. LangGraph callbacks preserve graph/node/tool/model parent IDs and
+concurrent runs. Avoid using both framework model callbacks and a provider wrapper for the same call.
+Provider packages remain optional; newer framework extras may require a newer Python than the core SDK.
+
+Options: `client=custom_client`, `name="my-agent"`, `capture_input=False`, `capture_output=False`.
+Existing redaction/size caps apply. Records include model, tokens, latency, TTFT, failures and raw usage
+metadata. Costs default to zero with `costKnown=False`; supply
+`calculate_cost=lambda usage: ...` with your own current provider rate card. The callback receives
+`provider`, `model`, `input_tokens`, `output_tokens`, and raw `usage` (including cache details).
+Missing usage is not estimated. Telemetry failures do not change provider results or exceptions.
+
+Anthropic total input tokens include uncached input plus cache reads and cache writes; the original
+usage breakdown remains in metadata for rate-card calculations. See the [provider’s token breakdown](https://platform.claude.com/docs/en/build-with-claude/prompt-caching).
+
+## Framework one-liners
+
+Quickest start: call `uncoil.init()` once at startup. Every OpenAI, Anthropic and LangChain / LangGraph call is traced, sync and async, with no client wrapping (`UNCOIL_API_KEY` is read from the environment). Libraries that are not installed are skipped, and `uncoil.uninit()` switches it off.
+
+```python
+import uncoil
+uncoil.init()
+```
+
+Calls made through a client you also wrapped with `wrap_openai` are recorded once, and model calls inside LangChain are recorded by the LangChain handler only. The Vercel AI SDK is JavaScript-only.
+
+```python
+import uncoil
+
+tools = uncoil.trace_tools({"search_docs": search_docs, "send_email": send_email})  # plain or async functions
+client = uncoil.wrap_openai(OpenAI())   # also wrap_anthropic, langgraph_callback
+```
+
+Copy-paste starters live in [`templates/`](./templates).
+
+## Sampling, redaction and clearer errors
+
+```python
+client = uncoil.UncoilClient(
+    sample_rate=0.1,                                   # record about 1 in 10 runs; each run is kept or dropped whole
+    redact={"patterns": [re.compile(r"ACME-\d{6}")]},  # emails, phones and card numbers are masked by default; add your own
+    on_error=lambda error: log(str(error)),            # problems come with a plain-language fix (error.hint)
+)
+```
+
+Spans that report an error are kept even when their run was not sampled (`keep_errors=False` turns that off). Secrets such as bearer tokens and API keys are always removed, and emails, phone numbers and card numbers are masked before anything leaves your app. To send them as they are, pass `redact={"pii": False}`.
+
+## Setup checker
+
+Not seeing traces? One command checks your key, region and network, then sends a test trace:
+
+```bash
+uncoil-doctor            # or: python -m uncoil doctor
+```
+
+It reads `UNCOIL_API_KEY` (and `UNCOIL_REGION` / `UNCOIL_HOST` if set), tells you in plain words what is wrong and how to fix it, and exits with code 1 if anything fails. Options: `--key`, `--region eu|us`, `--host`, `--no-send` (skip the test trace) and `--json`. The test trace is named "Uncoil setup check" and tagged `uncoil-doctor`; it counts as one trace on your plan.

uncoil_sdk-0.6.0/README.md

@@ -0,0 +1,198 @@
+# Uncoil Python SDK
+
+Observability and tracing for AI agents. Gain full visibility into your agent's decision-making process, tool usage, and LLM costs.
+
+Uncoil records each agent run as one trace: every model call, tool call, retry, failure and cost. It also ingests OpenTelemetry. Free plan available. Docs: [uncoil.dev/docs](https://www.uncoil.dev/docs). New to agent observability? Read the [complete guide](https://www.uncoil.dev/blog/ai-agent-observability-complete-guide).
+
+## Installation
+
+```bash
+pip install uncoil-sdk
+```
+
+## Quickstart
+
+1. Get your API Key from the [Uncoil Dashboard](https://www.uncoil.dev).
+2. Set it as an environment variable:
+
+```bash
+export UNCOIL_API_KEY=your_sk_live_...
+```
+
+3. Instrument your agent:
+
+```python
+from uncoil import trace_agent, llm_call, tool_call
+
+@trace_agent(environment="development", release="quickstart")
+async def my_agent(query: str):
+    # LLM Call
+    llm_call(
+        input_data=query,
+        output_data="Thinking...",
+        model_id="gpt-4o",
+        cost_usd=0.002,
+        latency_ms=800
+    )
+    
+    # Tool Use
+    tool_call(
+        tool_name="web_search",
+        input_data={"q": query},
+        output_data="Found results...",
+        latency_ms=1200
+    )
+    
+    return "Final Answer"
+```
+
+## Steps
+
+Inside a `@trace_agent` function, every step you record is linked to the step it ran in, so the trace graph
+shows which step called which and how loops repeat. Use `span` for a block and `observe` for a function:
+
+```python
+import uncoil
+
+@uncoil.observe(type="tool")
+def search_docs(query):
+    return search(query)
+
+@uncoil.trace_agent()
+def answer(question):
+    for turn in range(5):
+        with uncoil.span("think", type="agent"):
+            with uncoil.span("chat", type="llm", input=question) as step:
+                reply = call_model(question)
+                step.set_output(reply.text)
+                step.set(model="claude-sonnet-5-5", input_tokens=reply.usage.input, output_tokens=reply.usage.output)
+            if reply.done:
+                return reply.text
+            search_docs(reply.query)
+```
+
+`type` is one of `agent`, `llm`, `tool`, `retrieval` or `span`. Errors are recorded with their type and
+message. Concurrent runs (threads or asyncio tasks) stay in separate traces. Inputs and outputs have obvious
+secrets (bearer tokens, API keys, JWTs, `password=` values) removed and are capped at 10,000 characters;
+avoid sending anything else you would not want stored.
+
+## Features
+
+- **@trace_agent Decorator:** Automatically captures run lifecycle and errors.
+- **Granular Spans:** Manually record LLMs, tools, and custom decisions.
+- **Cost Tracking:** Monitor your infrastructure spend in real-time.
+- **Asynchronous & Synchronous Support:** Works with `async/await` or standard functions.
+- **Session context:** Attach `session_id`, `end_user_id`, `environment`, `release`, and `tags` to connect related traces.
+
+## Feedback and evaluation scores
+
+Pass `project_id` when constructing the client to attach end-user feedback and typed scores to traces:
+
+```python
+client = UncoilClient(project_id="your-project-id")
+client.feedback(run_id, True, kind="thumb", comment="Helpful answer")
+client.score(run_id, "answer_quality", 0.92, data_type="numeric")
+```
+
+Feedback and scores use the same API key as ingestion and do not interrupt the agent when delivery fails.
+
+## Prompt deployment
+
+Resolve a deployed prompt without shipping a new application build:
+
+```python
+deployed = client.get_prompt("support-agent", "production")
+client.ingest(spanType="llm", input=question, output=answer, promptVersionId=deployed["version"]["id"])
+```
+
+Prompt responses are cached for 60 seconds by default. Use `cache_ttl_seconds=0` or provide a `fallback` for development and guaranteed-availability behavior.
+
+## License
+
+MIT
+
+## Provider integrations (0.4.0)
+
+Install the optional provider/framework extras you use: `pip install 'uncoil-sdk[openai,anthropic,langgraph]'`.
+Set `UNCOIL_API_KEY` and the existing regional configuration.
+
+```python
+import uncoil
+from openai import OpenAI, AsyncOpenAI
+from anthropic import Anthropic
+
+openai = uncoil.wrap_openai(OpenAI())
+anthropic = uncoil.wrap_anthropic(Anthropic())
+async_openai = uncoil.wrap_openai(AsyncOpenAI())
+# Existing create calls keep their provider response types and exceptions.
+reply = openai.responses.create(model=MODEL, input="Hello")
+with anthropic.messages.stream(model=MODEL, max_tokens=100,
+        messages=[{"role": "user", "content": "Hello"}]) as stream:
+    for text in stream.text_stream:
+        print(text, end="")
+
+# Add a callback to a compiled LangGraph invocation.
+graph.invoke(inputs, config={"callbacks": [uncoil.langgraph_callback()]})
+```
+
+Wrap sync or async clients once. Supported: OpenAI chat completions and Responses `create` APIs,
+including streams; Anthropic messages `create`/`stream` and beta equivalents, including sync/async
+context managers, text streams and final messages. Close streams when stopping early. Raw response
+resources and unsupported convenience methods are passed through without instrumentation.
+
+Calls inside `trace_agent`/`span` inherit their run/parent and custom client. Standalone calls receive
+an independent completed root. LangGraph callbacks preserve graph/node/tool/model parent IDs and
+concurrent runs. Avoid using both framework model callbacks and a provider wrapper for the same call.
+Provider packages remain optional; newer framework extras may require a newer Python than the core SDK.
+
+Options: `client=custom_client`, `name="my-agent"`, `capture_input=False`, `capture_output=False`.
+Existing redaction/size caps apply. Records include model, tokens, latency, TTFT, failures and raw usage
+metadata. Costs default to zero with `costKnown=False`; supply
+`calculate_cost=lambda usage: ...` with your own current provider rate card. The callback receives
+`provider`, `model`, `input_tokens`, `output_tokens`, and raw `usage` (including cache details).
+Missing usage is not estimated. Telemetry failures do not change provider results or exceptions.
+
+Anthropic total input tokens include uncached input plus cache reads and cache writes; the original
+usage breakdown remains in metadata for rate-card calculations. See the [provider’s token breakdown](https://platform.claude.com/docs/en/build-with-claude/prompt-caching).
+
+## Framework one-liners
+
+Quickest start: call `uncoil.init()` once at startup. Every OpenAI, Anthropic and LangChain / LangGraph call is traced, sync and async, with no client wrapping (`UNCOIL_API_KEY` is read from the environment). Libraries that are not installed are skipped, and `uncoil.uninit()` switches it off.
+
+```python
+import uncoil
+uncoil.init()
+```
+
+Calls made through a client you also wrapped with `wrap_openai` are recorded once, and model calls inside LangChain are recorded by the LangChain handler only. The Vercel AI SDK is JavaScript-only.
+
+```python
+import uncoil
+
+tools = uncoil.trace_tools({"search_docs": search_docs, "send_email": send_email})  # plain or async functions
+client = uncoil.wrap_openai(OpenAI())   # also wrap_anthropic, langgraph_callback
+```
+
+Copy-paste starters live in [`templates/`](./templates).
+
+## Sampling, redaction and clearer errors
+
+```python
+client = uncoil.UncoilClient(
+    sample_rate=0.1,                                   # record about 1 in 10 runs; each run is kept or dropped whole
+    redact={"patterns": [re.compile(r"ACME-\d{6}")]},  # emails, phones and card numbers are masked by default; add your own
+    on_error=lambda error: log(str(error)),            # problems come with a plain-language fix (error.hint)
+)
+```
+
+Spans that report an error are kept even when their run was not sampled (`keep_errors=False` turns that off). Secrets such as bearer tokens and API keys are always removed, and emails, phone numbers and card numbers are masked before anything leaves your app. To send them as they are, pass `redact={"pii": False}`.
+
+## Setup checker
+
+Not seeing traces? One command checks your key, region and network, then sends a test trace:
+
+```bash
+uncoil-doctor            # or: python -m uncoil doctor
+```
+
+It reads `UNCOIL_API_KEY` (and `UNCOIL_REGION` / `UNCOIL_HOST` if set), tells you in plain words what is wrong and how to fix it, and exits with code 1 if anything fails. Options: `--key`, `--region eu|us`, `--host`, `--no-send` (skip the test trace) and `--json`. The test trace is named "Uncoil setup check" and tagged `uncoil-doctor`; it counts as one trace on your plan.

uncoil_sdk-0.6.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "uncoil-sdk"
+version = "0.6.0"
+authors = [
+  { name="Uncoil Team", email="hello@uncoil.dev" },
+]
+description = "Observability, runtime enforcement, and tracing for AI agents."
+license = "MIT"
+keywords = ["ai", "agents", "observability", "tracing", "llm", "llm-observability", "agent-tracing", "opentelemetry", "cost-tracking", "langchain", "openai", "anthropic"]
+readme = "README.md"
+requires-python = ">=3.7"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "requests>=2.25.0",
+    "httpx>=0.24.0",
+]
+
+[project.scripts]
+uncoil-doctor = "uncoil.doctor:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.urls]
+"Homepage" = "https://www.uncoil.dev"
+"Documentation" = "https://www.uncoil.dev/docs"
+"Bug Tracker" = "https://github.com/Uncoil-dev/Uncoil/issues"
+"Source" = "https://github.com/Uncoil-dev/Uncoil"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[project.optional-dependencies]
+openai = ["openai>=1.0"]
+anthropic = ["anthropic>=0.25"]
+langgraph = ["langchain-core>=0.2", "langgraph>=0.2"]
+test = ["pytest>=8", "pytest-asyncio>=0.24", "httpx2==2.13.1", "openai==3.31.0", "anthropic==1.14.0", "langgraph==1.2.15", "langchain-core==1.6.10"]

uncoil_sdk-0.6.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+