quraite 0.1.0__tar.gz → 0.1.1__tar.gz

quraite-0.1.1/PKG-INFO

@@ -0,0 +1,377 @@
+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.

quraite-0.1.1/README.md

@@ -0,0 +1,342 @@
+# 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.