agentbasis 0.1.0__tar.gz

agentbasis-0.1.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to the AgentBasis Python SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-01-19
+
+### Added
+
+- **Core SDK**: Initialize with `agentbasis.init(api_key, agent_id)`
+- **OpenTelemetry Integration**: Full OTel-based tracing with OTLP HTTP exporter
+- **Graceful Shutdown**: Automatic flush on exit via `atexit`
+
+#### LLM Integrations
+- **OpenAI**: Sync, async, and streaming support for Chat Completions
+- **Anthropic**: Sync, async, and streaming support for Messages API
+- **Gemini**: Sync, async, and streaming support for GenerativeModel
+
+#### Framework Integrations
+- **LangChain**: Callback handler with full parent-child span relationships
+- **Pydantic AI**: Integration via native OpenTelemetry support
+
+#### Context Management
+- User/session/conversation tracking with `set_user()`, `set_session()`, `set_conversation()`
+- Context manager pattern with `agentbasis.context()`
+- Decorator support with `@agentbasis.with_context()`
+
+#### Decorators
+- `@agentbasis.trace` for tracking any function (sync and async)
+
+### Documentation
+- Full documentation available at [docs.agentbasis.co](https://docs.agentbasis.co)

agentbasis-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,128 @@
+# Contributing to AgentBasis Python SDK
+
+Thank you for your interest in contributing to the AgentBasis Python SDK!
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.8 or higher
+- pip
+
+### Installation for Development
+
+1. Clone the repository:
+```bash
+git clone https://github.com/AgentBasis/agentbasis-python-sdk.git
+cd agentbasis-python-sdk
+```
+
+2. Install in development mode:
+```bash
+pip install -e .
+```
+
+3. Install development dependencies:
+```bash
+pip install pytest pytest-asyncio
+```
+
+## Building the Package
+
+After making changes, rebuild the package:
+
+```bash
+python -m build
+```
+
+This updates the distribution files in `dist/`.
+
+## Versioning & Releasing to PyPI
+
+We use [Semantic Versioning](https://semver.org/):
+
+| Change Type | Version Bump | Example |
+|-------------|--------------|---------|
+| Bug fix | Patch | `0.1.0` → `0.1.1` |
+| New feature (backward compatible) | Minor | `0.1.0` → `0.2.0` |
+| Breaking change | Major | `0.1.0` → `1.0.0` |
+
+### To Release a New Version
+
+1. Update the version in `pyproject.toml`:
+   ```toml
+   version = "0.1.1"
+   ```
+
+2. Update `CHANGELOG.md` with the changes
+
+3. Build the package:
+   ```bash
+   python -m build
+   ```
+
+4. Upload to PyPI:
+   ```bash
+   python -m twine upload dist/*
+   ```
+
+**Note:** PyPI does not allow overwriting existing versions. Once a version is published, you must increment the version number for any changes or fixes.
+
+## Testing Locally
+
+### Install from Local Build
+
+```bash
+pip install dist/agentbasis-0.1.0-py3-none-any.whl
+```
+
+### Install from GitHub (for testing before release)
+
+```bash
+pip install git+https://github.com/AgentBasis/agentbasis-python-sdk.git
+```
+
+### Run Unit Tests
+
+```bash
+python -m pytest tests/
+```
+
+## Project Structure
+
+```
+agentbasis/
+├── __init__.py          # Main entry point, init() function
+├── client.py            # AgentBasis client with OTel setup
+├── config.py            # Configuration handling
+├── context.py           # Context management (user, session, etc.)
+├── decorators.py        # @trace decorator
+├── llms/                # LLM provider integrations
+│   ├── openai/
+│   ├── anthropic/
+│   └── gemini/
+└── frameworks/          # Framework integrations
+    ├── langchain/
+    └── pydanticai/
+```
+
+## Code Style
+
+- Follow PEP 8 guidelines
+- Use type hints where possible
+- Add docstrings to public functions
+- Keep functions focused and single-purpose
+
+## Submitting Changes
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Make your changes
+4. Run tests to ensure nothing is broken
+5. Commit your changes (`git commit -am 'Add new feature'`)
+6. Push to the branch (`git push origin feature/my-feature`)
+7. Open a Pull Request
+
+## Questions?
+
+If you have questions, please reach out to support@agentbasis.co

agentbasis-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentBasis
+
+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.

agentbasis-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include CONTRIBUTING.md
+prune z-service-tests

agentbasis-0.1.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: agentbasis
+Version: 0.1.0
+Summary: Management & Observability SDK for AI Agents
+Author-email: AgentBasis <support@agentbasis.co>
+Maintainer-email: AgentBasis <support@agentbasis.co>
+Project-URL: Homepage, https://agentbasis.co
+Project-URL: Documentation, https://docs.agentbasis.co
+Project-URL: Repository, https://github.com/AgentBasis/agentbasis-python-sdk
+Project-URL: Bug Tracker, https://github.com/AgentBasis/agentbasis-python-sdk/issues
+Keywords: ai,agents,observability,tracing,opentelemetry,llm,openai,anthropic,langchain,monitoring,telemetry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: opentelemetry-api>=1.20.0
+Requires-Dist: opentelemetry-sdk>=1.20.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0
+
+# AgentBasis Python SDK
+
+**Management & Observability SDK for AI Agents in production**
+
+The **AgentBasis Python SDK** provides a simple, lightweight way to track the performance, traces, sessions, and behavior of AI agents. It sends data using the **OpenTelemetry (OTel)** standard, making it compatible with AgentBasis and other observability backends.
+
+This is the **foundation SDK** that enables deep observability for coded agents built with:
+- Pure Python
+- LLM Providers: 
+    - OpenAI
+    - Anthropic
+    - Gemini
+- Frameworks
+    - LangChain
+    - Pydantic AI
+
+## Installation
+
+```bash
+pip install agentbasis
+```
+
+## Quick Start
+
+### 1. Initialize the SDK
+Start by initializing the SDK with your API key and Agent ID. This usually goes at the top of your main application file.
+
+```python
+import agentbasis
+
+# Initialize with your API Key and Agent ID
+agentbasis.init(
+    api_key="your-api-key-here", 
+    agent_id="your-agent-id-here"
+)
+```
+
+### 2. Manual Tracking (Decorators)
+Use the `@trace` decorator to automatically track any function.
+
+```python
+from agentbasis import trace
+
+@trace
+def chat_with_user(query):
+    # Your agent logic here
+    return "Response to: " + query
+
+# When you call this, data is automatically sent to AgentBasis
+chat_with_user("Hello world")
+```
+
+### 3. OpenAI Integration
+Automatically track all your OpenAI calls (models, tokens, prompts) with one line of code.
+
+```python
+from agentbasis.llms.openai import instrument
+
+# Enable OpenAI instrumentation
+instrument()
+
+# Now just use the OpenAI client as normal
+from openai import OpenAI
+client = OpenAI()
+response = client.chat.completions.create(
+    model="gpt-4",
+    messages=[{"role": "user", "content": "Hello"}]
+)
+```
+
+### 4. Anthropic Integration
+Automatically track all your Anthropic Claude calls.
+
+```python
+from agentbasis.llms.anthropic import instrument
+
+# Enable Anthropic instrumentation
+instrument()
+
+# Now just use the Anthropic client as normal
+from anthropic import Anthropic
+client = Anthropic()
+response = client.messages.create(
+    model="claude-3-opus-20240229",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello"}]
+)
+```
+
+### 5. LangChain Integration
+Track chains, tools, retrievers, and LLM calls in LangChain with full parent-child span relationships.
+
+```python
+from agentbasis.frameworks.langchain import get_callback_handler
+
+# Create a callback handler
+handler = get_callback_handler()
+
+# Pass it to your LangChain calls
+from langchain_openai import ChatOpenAI
+llm = ChatOpenAI(model="gpt-4")
+response = llm.invoke("Hello world", config={"callbacks": [handler]})
+```
+
+For chains and agents, pass the callback handler in the config:
+
+```python
+from langchain.chains import LLMChain
+from langchain.prompts import PromptTemplate
+from agentbasis.frameworks.langchain import get_callback_config
+
+# Use get_callback_config() for convenience
+chain = LLMChain(llm=llm, prompt=PromptTemplate.from_template("{query}"))
+result = chain.invoke({"query": "What is AI?"}, config=get_callback_config())
+```
+
+### 6. Pydantic AI Integration
+Track Pydantic AI agents with built-in OpenTelemetry support.
+
+```python
+from agentbasis.frameworks.pydanticai import instrument
+
+# Enable global instrumentation for all Pydantic AI agents
+instrument()
+
+# Your agents are now automatically traced
+from pydantic_ai import Agent
+agent = Agent("openai:gpt-4")
+result = agent.run_sync("Hello!")
+```
+
+For per-agent control with user context:
+
+```python
+from agentbasis.frameworks.pydanticai import create_traced_agent
+
+# Create an agent pre-configured with tracing and context
+agent = create_traced_agent(
+    "openai:gpt-4",
+    system_prompt="You are a helpful assistant."
+)
+
+# Set user context - it will be included in traces
+agentbasis.set_user("user-123")
+result = agent.run_sync("Hello!")
+```
+
+### 7. Track Users & Sessions (Optional)
+Associate traces with specific users and sessions to debug issues and see per-user analytics.
+
+```python
+# Set the current user (from your auth system)
+agentbasis.set_user(current_user.id)
+
+# Optionally set session and conversation IDs
+agentbasis.set_session("session-abc")
+agentbasis.set_conversation("conv-123")
+
+# All subsequent LLM calls will be tagged with this context
+response = client.chat.completions.create(...)
+```
+
+Or use the context manager for scoped context:
+
+```python
+from agentbasis import context
+
+with context(user_id="user-123", session_id="session-abc"):
+    # All traces in this block include the context
+    response = client.chat.completions.create(...)
+```
+
+## Core Concepts
+
+- **OpenTelemetry**: We use OTel under the hood for maximum compatibility.
+- **Spans**: Every action (function call, LLM request) is recorded as a Span.
+- **Transport**: Data is batched and sent asynchronously to the AgentBasis backend.
+
+## Documentation
+
+For full documentation, visit [docs.agentbasis.co](https://docs.agentbasis.co).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+MIT License - see [LICENSE](LICENSE) for details.
+

agentbasis-0.1.0/README.md

@@ -0,0 +1,189 @@
+# AgentBasis Python SDK
+
+**Management & Observability SDK for AI Agents in production**
+
+The **AgentBasis Python SDK** provides a simple, lightweight way to track the performance, traces, sessions, and behavior of AI agents. It sends data using the **OpenTelemetry (OTel)** standard, making it compatible with AgentBasis and other observability backends.
+
+This is the **foundation SDK** that enables deep observability for coded agents built with:
+- Pure Python
+- LLM Providers: 
+    - OpenAI
+    - Anthropic
+    - Gemini
+- Frameworks
+    - LangChain
+    - Pydantic AI
+
+## Installation
+
+```bash
+pip install agentbasis
+```
+
+## Quick Start
+
+### 1. Initialize the SDK
+Start by initializing the SDK with your API key and Agent ID. This usually goes at the top of your main application file.
+
+```python
+import agentbasis
+
+# Initialize with your API Key and Agent ID
+agentbasis.init(
+    api_key="your-api-key-here", 
+    agent_id="your-agent-id-here"
+)
+```
+
+### 2. Manual Tracking (Decorators)
+Use the `@trace` decorator to automatically track any function.
+
+```python
+from agentbasis import trace
+
+@trace
+def chat_with_user(query):
+    # Your agent logic here
+    return "Response to: " + query
+
+# When you call this, data is automatically sent to AgentBasis
+chat_with_user("Hello world")
+```
+
+### 3. OpenAI Integration
+Automatically track all your OpenAI calls (models, tokens, prompts) with one line of code.
+
+```python
+from agentbasis.llms.openai import instrument
+
+# Enable OpenAI instrumentation
+instrument()
+
+# Now just use the OpenAI client as normal
+from openai import OpenAI
+client = OpenAI()
+response = client.chat.completions.create(
+    model="gpt-4",
+    messages=[{"role": "user", "content": "Hello"}]
+)
+```
+
+### 4. Anthropic Integration
+Automatically track all your Anthropic Claude calls.
+
+```python
+from agentbasis.llms.anthropic import instrument
+
+# Enable Anthropic instrumentation
+instrument()
+
+# Now just use the Anthropic client as normal
+from anthropic import Anthropic
+client = Anthropic()
+response = client.messages.create(
+    model="claude-3-opus-20240229",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello"}]
+)
+```
+
+### 5. LangChain Integration
+Track chains, tools, retrievers, and LLM calls in LangChain with full parent-child span relationships.
+
+```python
+from agentbasis.frameworks.langchain import get_callback_handler
+
+# Create a callback handler
+handler = get_callback_handler()
+
+# Pass it to your LangChain calls
+from langchain_openai import ChatOpenAI
+llm = ChatOpenAI(model="gpt-4")
+response = llm.invoke("Hello world", config={"callbacks": [handler]})
+```
+
+For chains and agents, pass the callback handler in the config:
+
+```python
+from langchain.chains import LLMChain
+from langchain.prompts import PromptTemplate
+from agentbasis.frameworks.langchain import get_callback_config
+
+# Use get_callback_config() for convenience
+chain = LLMChain(llm=llm, prompt=PromptTemplate.from_template("{query}"))
+result = chain.invoke({"query": "What is AI?"}, config=get_callback_config())
+```
+
+### 6. Pydantic AI Integration
+Track Pydantic AI agents with built-in OpenTelemetry support.
+
+```python
+from agentbasis.frameworks.pydanticai import instrument
+
+# Enable global instrumentation for all Pydantic AI agents
+instrument()
+
+# Your agents are now automatically traced
+from pydantic_ai import Agent
+agent = Agent("openai:gpt-4")
+result = agent.run_sync("Hello!")
+```
+
+For per-agent control with user context:
+
+```python
+from agentbasis.frameworks.pydanticai import create_traced_agent
+
+# Create an agent pre-configured with tracing and context
+agent = create_traced_agent(
+    "openai:gpt-4",
+    system_prompt="You are a helpful assistant."
+)
+
+# Set user context - it will be included in traces
+agentbasis.set_user("user-123")
+result = agent.run_sync("Hello!")
+```
+
+### 7. Track Users & Sessions (Optional)
+Associate traces with specific users and sessions to debug issues and see per-user analytics.
+
+```python
+# Set the current user (from your auth system)
+agentbasis.set_user(current_user.id)
+
+# Optionally set session and conversation IDs
+agentbasis.set_session("session-abc")
+agentbasis.set_conversation("conv-123")
+
+# All subsequent LLM calls will be tagged with this context
+response = client.chat.completions.create(...)
+```
+
+Or use the context manager for scoped context:
+
+```python
+from agentbasis import context
+
+with context(user_id="user-123", session_id="session-abc"):
+    # All traces in this block include the context
+    response = client.chat.completions.create(...)
+```
+
+## Core Concepts
+
+- **OpenTelemetry**: We use OTel under the hood for maximum compatibility.
+- **Spans**: Every action (function call, LLM request) is recorded as a Span.
+- **Transport**: Data is batched and sent asynchronously to the AgentBasis backend.
+
+## Documentation
+
+For full documentation, visit [docs.agentbasis.co](https://docs.agentbasis.co).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+MIT License - see [LICENSE](LICENSE) for details.
+

agentbasis-0.1.0/agentbasis/__init__.py

@@ -0,0 +1,87 @@
+from typing import Optional
+from .client import AgentBasis
+from .decorators import trace
+from .context import (
+    context,
+    set_user,
+    set_session,
+    set_conversation,
+    set_metadata,
+    with_context,
+    AgentBasisContext,
+)
+
+
+def init(api_key: Optional[str] = None, agent_id: Optional[str] = None) -> AgentBasis:
+    """
+    Initialize the AgentBasis SDK.
+    
+    Args:
+        api_key: Your AgentBasis API Key. If not provided, reads from AGENTBASIS_API_KEY env var.
+        agent_id: The ID of the agent to track. If not provided, reads from AGENTBASIS_AGENT_ID env var.
+    Returns:
+        The initialized AgentBasis client instance.
+    """
+    return AgentBasis.initialize(api_key=api_key, agent_id=agent_id)
+
+
+def flush(timeout_millis: int = 30000) -> bool:
+    """
+    Force flush all pending telemetry data.
+    
+    This is useful when you want to ensure all traces are sent before
+    a critical operation, at specific checkpoints, or before exiting.
+    
+    Note: The SDK automatically flushes on normal Python exit via atexit.
+    
+    Args:
+        timeout_millis: Maximum time to wait for flush (default 30 seconds).
+        
+    Returns:
+        True if flush completed successfully, False if timed out or not initialized.
+        
+    Example:
+        >>> agentbasis.init(api_key="...", agent_id="...")
+        >>> # ... your agent code ...
+        >>> agentbasis.flush()  # Ensure all data is sent
+    """
+    try:
+        client = AgentBasis.get_instance()
+        return client.flush(timeout_millis)
+    except RuntimeError:
+        # SDK not initialized
+        return False
+
+
+def shutdown():
+    """
+    Manually shut down the SDK and flush all pending data.
+    
+    This is automatically called on Python exit, but can be called
+    manually if you need to shut down the SDK before the process ends.
+    
+    This method is idempotent - calling it multiple times is safe.
+    """
+    try:
+        client = AgentBasis.get_instance()
+        client.shutdown()
+    except RuntimeError:
+        # SDK not initialized
+        pass
+
+
+__all__ = [
+    "init",
+    "AgentBasis",
+    "trace",
+    "flush",
+    "shutdown",
+    # Context management
+    "context",
+    "set_user",
+    "set_session",
+    "set_conversation",
+    "set_metadata",
+    "with_context",
+    "AgentBasisContext",
+]