Metadata-Version: 2.3
Name: quraite
Version: 0.1.1
Summary: This project provides adaptors and methods to integrate with the Quraite platform
Author: Shiv Mohith
Author-email: Shiv Mohith <shivmohith8@gmail.com>
Requires-Dist: aiohttp>=3.13.2
Requires-Dist: fastapi>=0.121.1
Requires-Dist: httpx>=0.28.1
Requires-Dist: openinference-semantic-conventions>=0.1.25
Requires-Dist: opentelemetry-api>=1.37.0
Requires-Dist: opentelemetry-sdk>=1.37.0
Requires-Dist: pydantic>=2.12.4
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: uvicorn>=0.38.0
Requires-Dist: agno>=2.3.4 ; extra == 'agno'
Requires-Dist: boto3>=1.40.70 ; extra == 'bedrock'
Requires-Dist: google-adk>=1.18.0 ; extra == 'google-adk'
Requires-Dist: langchain>=1.0.5 ; extra == 'langgraph'
Requires-Dist: langgraph>=1.0.3 ; extra == 'langgraph'
Requires-Dist: openai-agents>=0.5.0 ; extra == 'openai-agents'
Requires-Dist: pydantic-ai>=1.25.0 ; extra == 'pydantic-ai'
Requires-Dist: pyngrok>=7.5.0 ; extra == 'pyngrok'
Requires-Dist: smolagents>=1.23.0 ; extra == 'smolagents'
Requires-Python: >=3.10
Provides-Extra: agno
Provides-Extra: bedrock
Provides-Extra: google-adk
Provides-Extra: langgraph
Provides-Extra: openai-agents
Provides-Extra: pydantic-ai
Provides-Extra: pyngrok
Provides-Extra: smolagents
Description-Content-Type: text/markdown

# Quraite Python SDK

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

The **Quraite Python SDK** provides adapters and methods to integrate AI agent frameworks with the [Quraite platform](https://quraite.ai). It offers a unified interface for different agent frameworks, automatic tracing and observability, and easy local server setup with tunneling capabilities.

## Features

- 🔌 **Framework Adapters**: Support for multiple AI agent frameworks (LangGraph, Pydantic AI, Agno, Google ADK, OpenAI Agents, Smolagents, AWS Bedrock, Flowise, Langflow, N8n, and more)
- 📊 **Automatic Tracing**: Built-in OpenTelemetry-based tracing for agent execution, tool calls, and performance metrics
- 🚀 **Local Server**: Easy-to-use local server with optional tunneling (Cloudflare/ngrok) for public access
- 📦 **Standardized Schema**: Unified message and response formats across all frameworks
- 🔍 **Observability**: Track token usage, costs, latency, and model information for each agent invocation

## Installation

### Basic Installation

```bash
pip install quraite
```

### Framework-Specific Installation

Install with optional dependencies for specific frameworks:

```bash
# LangGraph
pip install 'quraite[langgraph]'

# Pydantic AI
pip install 'quraite[pydantic-ai]'

# Agno
pip install 'quraite[agno]'

# Google ADK
pip install 'quraite[google-adk]'

# OpenAI Agents
pip install 'quraite[openai-agents]'

# Smolagents
pip install 'quraite[smolagents]'

# AWS Bedrock
pip install 'quraite[bedrock]'

# Multiple frameworks
pip install 'quraite[langgraph,pydantic-ai,agno]'
```

## Quick Start

### Example: LangGraph Agent with Local Server

Pass your compiled LangGraph agent to the adapter and expose it as an HTTP API:

```python
import uvicorn
from dotenv import load_dotenv
from openinference.instrumentation import TracerProvider
from openinference.instrumentation.langchain import LangChainInstrumentor

from quraite.adapters import LanggraphAdapter
from quraite.serve.local_agent import LocalAgentServer
from quraite.tracing.span_exporter import QuraiteInMemorySpanExporter
from quraite.tracing.span_processor import QuraiteSimpleSpanProcessor

load_dotenv()

# Set up tracing (optional)
tracer_provider = TracerProvider()
quraite_span_exporter = QuraiteInMemorySpanExporter()
quraite_span_processor = QuraiteSimpleSpanProcessor(quraite_span_exporter)
tracer_provider.add_span_processor(quraite_span_processor)
LangChainInstrumentor().instrument(tracer_provider=tracer_provider)

# Your compiled LangGraph agent (created elsewhere)
# agent = create_agent(...)

# Wrap with Quraite adapter
adapter = LanggraphAdapter(
    agent_graph=agent,  # Pass your compiled LangGraph agent here
    tracer_provider=tracer_provider,  # Optional: for tracing
)

# Create and start server with Cloudflare tunnel
server = LocalAgentServer(
    wrapped_agent=adapter,
    agent_id="your-agent-id",  # Optional: for Quraite platform integration
)

app = server.create_app(
    port=8080,
    host="0.0.0.0",
    tunnel="cloudflare",  # Options: "cloudflare", "ngrok", or "none"
)

if __name__ == "__main__":
    uvicorn.run("local_server:app", host="0.0.0.0", port=8080)
```

The server exposes:

- `GET /` - Health check endpoint
- `POST /v1/agents/completions` - Agent invocation endpoint

When using `tunnel="cloudflare"` or `tunnel="ngrok"`, your agent will be publicly accessible via the generated URL.

## Supported Frameworks

| Framework            | Adapter                  | Installation                           |
| -------------------- | ------------------------ | -------------------------------------- |
| **LangGraph**        | `LanggraphAdapter`       | `pip install 'quraite[langgraph]'`     |
| **Pydantic AI**      | `PydanticAIAdapter`      | `pip install 'quraite[pydantic-ai]'`   |
| **Agno**             | `AgnoAdapter`            | `pip install 'quraite[agno]'`          |
| **Google ADK**       | `GoogleADKAdapter`       | `pip install 'quraite[google-adk]'`    |
| **OpenAI Agents**    | `OpenaiAgentsAdapter`    | `pip install 'quraite[openai-agents]'` |
| **Smolagents**       | `SmolagentsAdapter`      | `pip install 'quraite[smolagents]'`    |
| **AWS Bedrock**      | `BedrockAgentsAdapter`   | `pip install 'quraite[bedrock]'`       |
| **Flowise**          | `FlowiseAdapter`         | Included in base package               |
| **Langflow**         | `LangflowAdapter`        | Included in base package               |
| **N8n**              | `N8nAdapter`             | Included in base package               |
| **HTTP**             | `HttpAdapter`            | Included in base package               |
| **LangGraph Server** | `LanggraphServerAdapter` | `pip install 'quraite[langgraph]'`     |

## Core Concepts

### Adapters

Adapters provide a unified interface (`BaseAdapter`) for different agent frameworks. Each adapter:

- Converts framework-specific agents to a standard interface
- Handles message format conversion
- Supports optional tracing integration
- Provides async invocation via `ainvoke()`

### Tracing

The SDK includes built-in OpenTelemetry-based tracing that captures:

- **Agent Trajectory**: Complete conversation flow with all messages
- **Tool Calls**: Tool invocations with inputs and outputs
- **Performance Metrics**: Token usage, costs, latency
- **Model Information**: Model name and provider details

To enable tracing:

```python
from openinference.instrumentation import TracerProvider
from quraite.tracing.span_exporter import QuraiteInMemorySpanExporter
from quraite.tracing.span_processor import QuraiteSimpleSpanProcessor

tracer_provider = TracerProvider()
quraite_span_exporter = QuraiteInMemorySpanExporter()
quraite_span_processor = QuraiteSimpleSpanProcessor(quraite_span_exporter)
tracer_provider.add_span_processor(quraite_span_processor)

# Instrument your framework (example for LangChain)
from openinference.instrumentation.langchain import LangChainInstrumentor
LangChainInstrumentor().instrument(tracer_provider=tracer_provider)
```

### Message Schema

The SDK uses a standardized message format:

```python
from quraite.schema.message import (
    UserMessage,
    AssistantMessage,
    ToolMessage,
    SystemMessage,
    MessageContentText,
    ToolCall,
)

# User message
user_msg = UserMessage(
    content=[MessageContentText(text="Hello, world!")]
)

# Assistant message with tool calls
assistant_msg = AssistantMessage(
    content=[MessageContentText(text="I'll calculate that for you.")],
    tool_calls=[
        ToolCall(
            id="call_123",
            name="add",
            arguments={"a": 10, "b": 5}
        )
    ]
)

# Tool message
tool_msg = ToolMessage(
    tool_call_id="call_123",
    content=[MessageContentText(text="15")]
)
```

### Response Format

Agent invocations return an `AgentInvocationResponse`:

```python
from quraite.schema.response import AgentInvocationResponse

response: AgentInvocationResponse = await adapter.ainvoke(
    input=[user_msg],
    session_id="session-123"
)

# Access trajectory (list of messages)
trajectory = response.agent_trajectory

# Access trace (if tracing enabled)
trace = response.agent_trace

# Access final response text
final_response = response.agent_final_response
```

## Examples

The repository includes comprehensive examples for each supported framework:

- [`langgraph_calculator_agent`](examples/langgraph_calculator_agent/) - LangGraph calculator agent
- [`pydantic_calculator_agent`](examples/pydantic_calculator_agent/) - Pydantic AI calculator agent
- [`agno_calculator_agent`](examples/agno_calculator_agent/) - Agno calculator agent
- [`google_adk_weather_agent`](examples/google_adk_weather_agent/) - Google ADK weather agent
- [`openai_flight_booking_agent`](examples/openai_flight_booking_agent/) - OpenAI Agents flight booking
- [`smolagents_sql_agent`](examples/smolagents_sql_agent/) - Smolagents SQL agent
- [`bedrock_restaurant_support_agent`](examples/bedrock_restaurant_support_agent/) - AWS Bedrock agent
- And more...

Each example includes:

- Agent implementation
- Adapter setup
- Local server configuration
- Environment variable examples

## API Reference

### BaseAdapter

All adapters inherit from `BaseAdapter`:

```python
from quraite.adapters.base import BaseAdapter

class MyAdapter(BaseAdapter):
    async def ainvoke(
        self,
        input: List[AgentMessage],
        session_id: str | None,
    ) -> AgentInvocationResponse:
        # Implementation
        pass
```

### LocalAgentServer

Create a local HTTP server for your agent:

```python
from quraite.serve.local_agent import LocalAgentServer

server = LocalAgentServer(
    wrapped_agent=adapter,
    agent_id="optional-agent-id",
)

app = server.create_app(
    port=8080,
    host="0.0.0.0",
    tunnel="cloudflare",  # or "ngrok" or "none"
)
```

## Development

### Setup

```bash
# Clone the repository
git clone https://github.com/innowhyte/quraite-python.git
cd quraite-python

# Install dependencies
pip install -e ".[dev,test]"
```

### Running Tests

```bash
pytest
```

### Building

```bash
make build
```

### Publishing

```bash
# Update version
make update-version v=0.4.0

# Build
make build

# Publish to Test PyPI
make publish
# Enter username as "__token__" and then enter your API key
```

## Requirements

- Python 3.10+
- See `pyproject.toml` for full dependency list

## License

See [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

For issues, questions, or contributions, please visit the [Quraite platform](https://quraite.ai) or open an issue on GitHub.

## Changelog

See the repository's commit history for detailed changes.
