quraite 0.1.4

This project provides adaptors and methods to integrate with the Quraite platform

Quraite Python SDK

The Quraite Python SDK provides adapters and methods to integrate AI agent with the Quraite platform for evaluation. It offers a unified interface for different agent frameworks, automatic tracing at every turn for agent trajectory evaluation, and easy local server setup with tunneling capabilities.

Features

• 🔌 Framework Adapters: Support for multiple AI agent frameworks (LangChain, Pydantic AI, Agno, Google ADK, OpenAI Agents, Smolagents, AWS Bedrock, Flowise, Langflow, N8n, and more)
• 📊 Automatic Tracing: Built-in OpenInference-based (OpenTelemetry-based tracing support coming soon) tracing for agent trajectory evaluation. Track token usage, costs, latency, and model information for each agent invocation
• 🚀 Local Server: Easy-to-use local server with optional tunneling (Cloudflare/ngrok) for public access and integration with Quraite platform

Installation

Basic Installation

pip install quraite

Framework-Specific Installation

Install with optional dependencies for specific frameworks:

# LangChain
pip install 'quraite[langchain]'

# 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[langchain,pydantic-ai,agno]'

Quick Start

Example: LangChain Agent with Local Server

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

from dotenv import load_dotenv

from quraite import run_agent
from quraite.adapters import LangchainAdapter
from quraite.tracing import Framework, setup_tracing

load_dotenv()

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

# Setup tracing once
tracer_provider = setup_tracing([Framework.LANGCHAIN])

# Create adapter with tracer provider
adapter = LangchainAdapter(
    agent_graph=agent,  # Pass your compiled LangChain agent here
    tracer_provider=tracer_provider,
)

# Option 1: Use run_agent to start the server (simplest)
run_agent(
    adapter,
    agent_id="your-agent-id",  # Optional: for Quraite platform integration
    port=8080,
    host="0.0.0.0",
    tunnel="cloudflare",  # Options: "cloudflare", "ngrok", or "none"
)

# Option 2: Use create_app for more control (e.g., with uvicorn reload)
from quraite import create_app
import uvicorn

app = create_app(adapter, agent_id="your-agent-id")

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

The server exposes:

• GET / - Health check endpoint
• POST /v1/agents/completions - Agent invocation endpoint. This is the endpoint that Quraite will use to invoke your agent.

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

Supported Frameworks

Framework	Adapter	Installation
LangChain	LangChainAdapter	pip install 'quraite[langchain]'
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
LangChain Server	LangChainServerAdapter	pip install 'quraite[langchain]'

Core Concepts

Adapters

Adapters provide a unified interface (BaseAdapter) for different agent frameworks. Each adapter converts framework-specific agent response formats to the Quraite agent message format.

If you are building your own agent framework, you can create a custom adapter by extending the BaseAdapter class and implementing the ainvoke method.

Tracing for Agent Trajectory Evaluation

Capture agent trajectories without modifying your code. Get comprehensive trace data including token usage, costs, and latency for every agent step.

Most agent frameworks return agent steps, but lack critical observability data. We solve this with OpenInference instrumentation (OpenTelemetry instrumentation support coming soon) that automatically captures:

• Complete agent trajectories
• Token usage and costs
• Step-by-step latency
• Full execution context

Works with your existing setup. We provide OpenInference-compatible span exporters and processors that integrate seamlessly with your current observability platform - no vendor lock-in required.

To enable tracing:

from quraite.tracing import Framework, setup_tracing

# Setup tracing once at app startup
tracer_provider = setup_tracing([Framework.LANGCHAIN])

# Pass to adapter
from quraite.adapters import LangchainAdapter
adapter = LangchainAdapter(agent_graph=agent, tracer_provider=tracer_provider)

Message Schema

The SDK uses a standardized message format:

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")]
)

Invoke Input and Output

Agent invocations use structured InvokeInput and return InvokeOutput:

from quraite.schema.invoke import InvokeInput, InvokeOutput

response: InvokeOutput = await adapter.ainvoke(
    input=InvokeInput(
        user_message=user_msg,
        session_id="session-123"
    )
)

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

# Access trace
trace = response.agent_trace

Examples

The repository includes comprehensive examples for each supported framework:

• langchain_calculator_agent - LangChain calculator agent
• pydantic_calculator_agent - Pydantic AI calculator agent
• agno_calculator_agent - Agno calculator agent
• google_adk_weather_agent - Google ADK weather agent
• openai_flight_booking_agent - OpenAI Agents flight booking
• smolagents_sql_agent - Smolagents SQL agent
• 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:

from quraite.adapters.base import BaseAdapter
from quraite.schema.invoke import InvokeInput, InvokeOutput

class MyAdapter(BaseAdapter):
    async def ainvoke(
        self,
        input: InvokeInput,
    ) -> InvokeOutput:
        # Implementation
        # Access user_message: input.user_message
        # Access session_id: input.session_id
        pass

Running Your Agent

Use run_agent or create_app to start a local HTTP server for your agent:

from quraite import run_agent, create_app

# Simple approach: run_agent handles everything
run_agent(
    adapter,
    agent_id="optional-agent-id",
    port=8080,
    host="0.0.0.0",
    tunnel="cloudflare",  # or "ngrok" or "none"
)

# Advanced approach: create_app for more control (e.g., uvicorn reload)
import uvicorn

app = create_app(
    adapter,
    agent_id="optional-agent-id",
)

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

Development

Setup

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

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

Running Tests

pytest

Building

make build

Publishing

# 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 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 or open an issue on GitHub.

Changelog

See the repository's commit history for detailed changes.