agentq 0.1.0__tar.gz

agentq-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: agentq
+Version: 0.1.0
+Summary: AgentQ SDK — agent observability for Python.
+Author: Ryan Dao
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ryandao/agentq
+Project-URL: Repository, https://github.com/ryandao/agentq
+Project-URL: Issues, https://github.com/ryandao/agentq/issues
+Keywords: observability,ai-agents,llm,tracing,opentelemetry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: opentelemetry-api>=1.20
+Requires-Dist: opentelemetry-sdk>=1.20
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.20; extra == "anthropic"
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.0; extra == "gemini"
+Provides-Extra: celery
+Requires-Dist: celery>=5.0; extra == "celery"
+Provides-Extra: all
+Requires-Dist: openai>=1.0; extra == "all"
+Requires-Dist: anthropic>=0.20; extra == "all"
+Requires-Dist: google-genai>=1.0; extra == "all"
+Requires-Dist: celery>=5.0; extra == "all"
+
+# AgentQ SDK
+
+A Python SDK for instrumenting AI agents with observability. Traces agent runs, LLM calls, and tool invocations, sending data to an AgentQ server via OpenTelemetry.
+
+## Installation
+
+```bash
+pip install agentq
+```
+
+For auto-instrumentation of specific LLM providers, install them alongside:
+
+```bash
+pip install agentq openai anthropic google-genai
+```
+
+## Quick Start
+
+```python
+import agentq
+
+# Point to your AgentQ server
+agentq.init(endpoint="http://localhost:3000")
+
+# Auto-patch supported LLM libraries
+agentq.instrument()
+
+@agentq.agent(name="my-agent")
+def run_task(prompt: str) -> str:
+    # Any OpenAI/Anthropic/Gemini calls inside here are traced automatically
+    response = openai.chat.completions.create(
+        model="gpt-4",
+        messages=[{"role": "user", "content": prompt}],
+    )
+    return response.choices[0].message.content
+```
+
+## Features
+
+- **`@agent` decorator** -- Wraps functions and classes to create traced runs with input/output capture
+- **Auto-instrumentation** -- Monkey-patches OpenAI, Anthropic, and Google Gemini to trace every LLM call
+- **Session tracking** -- Group related runs into sessions with the `session` context manager
+- **Nested spans** -- Nested `@agent` calls and manual `track_agent`/`track_llm`/`track_tool` spans
+- **Celery integration** -- Captures queue wait time for Celery tasks
+- **OpenTelemetry native** -- Built on OpenTelemetry, compatible with any OTLP endpoint
+
+## API Reference
+
+### `agentq.init(endpoint, headers, service_name)`
+
+Initialize the SDK. Call once at startup.
+
+- `endpoint` -- OTLP HTTP base URL (e.g. `http://localhost:3000`). Falls back to `OTEL_EXPORTER_OTLP_ENDPOINT`.
+- `headers` -- Extra headers for OTLP requests (e.g. `{"Authorization": "Bearer sk-xxx"}`).
+- `service_name` -- Value for the `service.name` resource attribute (default: `"agentq"`).
+
+### `agentq.instrument()`
+
+Activate auto-instrumentation for OpenAI, Anthropic, Google Gemini, and Celery. Safe to call even if libraries aren't installed.
+
+### `@agentq.agent(name, entry_method, description, version, metadata)`
+
+Decorator for functions or classes. Creates a traced run for each invocation.
+
+For classes, `entry_method` specifies which method(s) to instrument (default: `"execute"`).
+
+### `agentq.session(name, session_id, run_id, metadata)`
+
+Context manager that groups runs into a session:
+
+```python
+with agentq.session(name="user-chat"):
+    run_task("Hello")
+    run_task("Follow up")
+```
+
+### Manual Span Context Managers
+
+```python
+with agentq.track_agent("sub-agent") as span:
+    ...
+
+with agentq.track_llm("gpt-4") as span:
+    ...
+
+with agentq.track_tool("web-search") as span:
+    ...
+```
+
+## License
+
+[MIT](../LICENSE)

agentq-0.1.0/README.md

@@ -0,0 +1,92 @@
+# AgentQ SDK
+
+A Python SDK for instrumenting AI agents with observability. Traces agent runs, LLM calls, and tool invocations, sending data to an AgentQ server via OpenTelemetry.
+
+## Installation
+
+```bash
+pip install agentq
+```
+
+For auto-instrumentation of specific LLM providers, install them alongside:
+
+```bash
+pip install agentq openai anthropic google-genai
+```
+
+## Quick Start
+
+```python
+import agentq
+
+# Point to your AgentQ server
+agentq.init(endpoint="http://localhost:3000")
+
+# Auto-patch supported LLM libraries
+agentq.instrument()
+
+@agentq.agent(name="my-agent")
+def run_task(prompt: str) -> str:
+    # Any OpenAI/Anthropic/Gemini calls inside here are traced automatically
+    response = openai.chat.completions.create(
+        model="gpt-4",
+        messages=[{"role": "user", "content": prompt}],
+    )
+    return response.choices[0].message.content
+```
+
+## Features
+
+- **`@agent` decorator** -- Wraps functions and classes to create traced runs with input/output capture
+- **Auto-instrumentation** -- Monkey-patches OpenAI, Anthropic, and Google Gemini to trace every LLM call
+- **Session tracking** -- Group related runs into sessions with the `session` context manager
+- **Nested spans** -- Nested `@agent` calls and manual `track_agent`/`track_llm`/`track_tool` spans
+- **Celery integration** -- Captures queue wait time for Celery tasks
+- **OpenTelemetry native** -- Built on OpenTelemetry, compatible with any OTLP endpoint
+
+## API Reference
+
+### `agentq.init(endpoint, headers, service_name)`
+
+Initialize the SDK. Call once at startup.
+
+- `endpoint` -- OTLP HTTP base URL (e.g. `http://localhost:3000`). Falls back to `OTEL_EXPORTER_OTLP_ENDPOINT`.
+- `headers` -- Extra headers for OTLP requests (e.g. `{"Authorization": "Bearer sk-xxx"}`).
+- `service_name` -- Value for the `service.name` resource attribute (default: `"agentq"`).
+
+### `agentq.instrument()`
+
+Activate auto-instrumentation for OpenAI, Anthropic, Google Gemini, and Celery. Safe to call even if libraries aren't installed.
+
+### `@agentq.agent(name, entry_method, description, version, metadata)`
+
+Decorator for functions or classes. Creates a traced run for each invocation.
+
+For classes, `entry_method` specifies which method(s) to instrument (default: `"execute"`).
+
+### `agentq.session(name, session_id, run_id, metadata)`
+
+Context manager that groups runs into a session:
+
+```python
+with agentq.session(name="user-chat"):
+    run_task("Hello")
+    run_task("Follow up")
+```
+
+### Manual Span Context Managers
+
+```python
+with agentq.track_agent("sub-agent") as span:
+    ...
+
+with agentq.track_llm("gpt-4") as span:
+    ...
+
+with agentq.track_tool("web-search") as span:
+    ...
+```
+
+## License
+
+[MIT](../LICENSE)

agentq-0.1.0/agentq/__init__.py

@@ -0,0 +1,22 @@
+from agentq.registry import init, instrument
+from agentq.instrumentation import (
+    agent,
+    session,
+    current_span,
+    track_agent,
+    track_llm,
+    track_tool,
+    ObservabilityLogHandler,
+)
+
+__all__ = [
+    "init",
+    "instrument",
+    "agent",
+    "session",
+    "current_span",
+    "track_agent",
+    "track_llm",
+    "track_tool",
+    "ObservabilityLogHandler",
+]