quraite 0.1.2__py3-none-any.whl → 0.1.4__py3-none-any.whl

quraite/schema/__init__.py

@@ -0,0 +1,4 @@
+from quraite.schema.invoke import InvokeInput, InvokeOutput
+from quraite.schema.message import UserMessage
+
+__all__ = ["UserMessage", "InvokeInput", "InvokeOutput"]

quraite/schema/invoke.py

@@ -0,0 +1,46 @@
+"""Request and response models for agent invocation endpoints."""
+
+
+from collections.abc import Sequence
+
+from pydantic import BaseModel
+
+from quraite.schema.message import AgentMessage, UserMessage
+from quraite.tracing.trace import AgentTrace
+
+
+class InvokeInput(BaseModel):
+    """
+    Request model for agent invocation endpoints.
+
+    Attributes:
+        user_message: UserMessage object
+        session_id: Optional conversation thread identifier
+    """
+
+    user_message: UserMessage
+    session_id: str | None = None
+
+    def user_message_str(self) -> str:
+        """Extract text content from user message."""
+        if not self.user_message.content:
+            raise ValueError("User message has no content")
+
+        for content_item in self.user_message.content:
+            if content_item.type == "text" and content_item.text:
+                return content_item.text
+
+        raise ValueError("No text content found in user message")
+
+
+class InvokeOutput(BaseModel):
+    """
+    Output model for agent invocation endpoints.
+
+    Attributes:
+        agent_trace: AgentTrace object representing agent trace
+        agent_trajectory: List of AgentMessage objects representing agent trajectory
+    """
+
+    agent_trace: AgentTrace | None = None
+    agent_trajectory: Sequence[AgentMessage] | None = None

quraite/schema/message.py

@@ -1,4 +1,5 @@
-from typing import Any, List, Literal, Optional, TypeAlias, Union
+from collections.abc import Sequence
+from typing import Any, Literal, TypeAlias
 
 from pydantic import BaseModel, Field
 
@@ -15,18 +16,18 @@ class MessageContentReasoning(BaseModel):
 
 class UserMessage(BaseModel):
     role: Literal["user"] = "user"
-    name: Optional[str] = None
-    content: List[MessageContentText]
+    name: str | None = None
+    content: list[MessageContentText]
 
 
 class DeveloperMessage(BaseModel):
     role: Literal["developer"] = "developer"
-    content: List[MessageContentText]
+    content: list[MessageContentText]
 
 
 class SystemMessage(BaseModel):
     role: Literal["system"] = "system"
-    content: List[MessageContentText]
+    content: list[MessageContentText]
 
 
 class ToolCall(BaseModel):
@@ -58,34 +59,32 @@ class LatencyInfo(BaseModel):
 class AssistantMessageMetadata(BaseModel):
     """Structured metadata for assistant messages."""
 
-    tokens: TokenInfo = Field(default_factory=TokenInfo)
-    cost: CostInfo = Field(default_factory=CostInfo)
-    latency: LatencyInfo = Field(default_factory=LatencyInfo)
-    model_info: ModelInfo = Field(default_factory=ModelInfo)
+    tokens: TokenInfo | None = None
+    cost: CostInfo | None = None
+    latency: LatencyInfo | None = None
+    model_info: ModelInfo | None = None
 
 
 class ToolMessageMetadata(BaseModel):
     """Structured metadata for tool messages."""
 
-    latency: LatencyInfo = Field(default_factory=LatencyInfo)
+    latency: LatencyInfo | None = None
 
 
 class AssistantMessage(BaseModel):
     role: Literal["assistant"] = "assistant"
-    agent_name: Optional[str] = None
-    content: Optional[List[Union[MessageContentText, MessageContentReasoning]]] = None
-    tool_calls: Optional[List[ToolCall]] = None
-    metadata: AssistantMessageMetadata = Field(default_factory=AssistantMessageMetadata)
+    agent_name: str | None = None
+    content: Sequence[MessageContentText | MessageContentReasoning] | None = None
+    tool_calls: list[ToolCall] | None = None
+    metadata: AssistantMessageMetadata | None = None
 
 
 class ToolMessage(BaseModel):
     role: Literal["tool"] = "tool"
-    tool_name: Optional[str] = None
-    tool_call_id: Optional[str] = None
-    content: List[MessageContentText]
-    metadata: ToolMessageMetadata = Field(default_factory=ToolMessageMetadata)
+    tool_name: str | None = None
+    tool_call_id: str | None = None
+    content: list[MessageContentText]
+    metadata: ToolMessageMetadata | None = None
 
 
-AgentMessage: TypeAlias = Union[
-    UserMessage, DeveloperMessage, SystemMessage, AssistantMessage, ToolMessage
-]
+AgentMessage: TypeAlias = UserMessage | DeveloperMessage | SystemMessage | AssistantMessage | ToolMessage

quraite/serve/__init__.py

@@ -1 +1,5 @@
+"""Quraite serving utilities."""
 
+from quraite.serve.server import create_app, run_agent, setup_tunnel
+
+__all__ = ["create_app", "run_agent", "setup_tunnel"]

quraite/serve/cloudflared.py

@@ -105,8 +105,9 @@ def download_cloudflared(force: bool = False) -> Path:
     cloudflared_cmd = (
         "cloudflared.exe" if platform.system() == "windows" else "cloudflared"
     )
-    if shutil.which(cloudflared_cmd) and not force:
-        return Path(shutil.which(cloudflared_cmd))
+    cloudflared_in_path = shutil.which(cloudflared_cmd)
+    if cloudflared_in_path and not force:
+        return Path(cloudflared_in_path)
 
     cloudflared_path = get_cloudflared_path()
     system_key = get_system()

quraite/serve/server.py

@@ -0,0 +1,305 @@
+"""Simplified agent runner API for Quraite."""
+
+import asyncio
+import os
+from typing import Any, Literal
+
+import httpx
+import uvicorn
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+
+from quraite.adapters.base import BaseAdapter
+from quraite.logger import get_logger
+from quraite.schema import InvokeInput, InvokeOutput
+
+logger = get_logger(__name__)
+
+
+class TunnelConfig(BaseModel):
+    tunnel_obj: Any
+    agent_url: str
+    tunnel_type: Literal["ngrok", "cloudflare", "none"]
+
+
+def setup_tunnel(
+    port: int,
+    host: str = "0.0.0.0",
+    tunnel: Literal["ngrok", "cloudflare"] = "cloudflare",
+) -> TunnelConfig:
+    """
+    Setup tunnel connection.
+
+    Args:
+        port: Local port to expose
+        host: Local host address
+        tunnel: Tunnel type
+
+    Returns:
+        Tuple of (public_url, tunnel_object)
+    """
+    if tunnel == "ngrok":
+        try:
+            from pyngrok import ngrok
+        except ImportError as e:
+            raise ImportError(
+                "Failed to import pyngrok. Install with: pip install 'quraite[pyngrok]'"
+            ) from e
+
+        try:
+            ngrok_tunnel = ngrok.connect(port)
+            public_url = ngrok_tunnel.public_url
+            logger.info("Ngrok tunnel established: %s", public_url)
+            return TunnelConfig(
+                tunnel_obj=ngrok_tunnel, agent_url=public_url, tunnel_type="ngrok"
+            )
+        except Exception as e:
+            logger.error(
+                "Failed to create ngrok tunnel: %s. "
+                "Make sure ngrok is installed and authenticated: https://ngrok.com/download",
+                e,
+            )
+            raise
+
+    elif tunnel == "cloudflare":
+        from quraite.serve.cloudflared import connect
+
+        cloudflared_tunnel = connect(
+            port, host=host if host != "0.0.0.0" else "localhost"
+        )
+        public_url = cloudflared_tunnel.public_url
+        logger.info("Cloudflare tunnel established: %s", public_url)
+        return TunnelConfig(
+            tunnel_obj=cloudflared_tunnel,
+            agent_url=public_url,
+            tunnel_type="cloudflare",
+        )
+
+
+def _cleanup_tunnel(tunnel_obj: Any, tunnel_type: Literal["ngrok", "cloudflare", "none"]) -> None:
+    """Clean up tunnel connection."""
+    try:
+        if tunnel_type == "ngrok":
+            from pyngrok import ngrok
+
+            ngrok.disconnect(tunnel_obj.public_url)
+            ngrok.kill()
+            logger.info("Ngrok tunnel closed")
+        elif tunnel_type == "cloudflare":
+            if hasattr(tunnel_obj, "disconnect"):
+                tunnel_obj.disconnect()
+            elif hasattr(tunnel_obj, "stop"):
+                tunnel_obj.stop()
+            elif hasattr(tunnel_obj, "close"):
+                tunnel_obj.close()
+            logger.info("Cloudflare tunnel closed")
+    except Exception as e:
+        logger.warning("Error closing %s tunnel: %s", tunnel_type, e)
+
+
+async def _update_backend_agent_url(
+    agent_id: str,
+    agent_url: str | None,
+    quraite_endpoint: str = "https://api.quraite.ai",
+) -> None:
+    """
+    Update backend with agent URL.
+
+    Args:
+        agent_id: Quraite platform agent ID
+        agent_url: Agent base URL
+        quraite_endpoint: Quraite API endpoint
+    """
+    if not agent_id or not agent_url:
+        return
+
+    endpoint = f"{quraite_endpoint.rstrip('/')}/agents/{agent_id}/config/url"
+    full_url = f"{agent_url.rstrip('/')}/v1/agents/completions"
+    payload = {"config": {"url": full_url}}
+
+    try:
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            response = await client.patch(endpoint, json=payload)
+            response.raise_for_status()
+            logger.info("Agent URL registered with Quraite platform: %s", full_url)
+    except httpx.HTTPStatusError as e:
+        logger.warning(
+            "Failed to update agent URL in Quraite platform: HTTP %s - %s. Update manually with URL: %s",
+            e.response.status_code,
+            e.response.text,
+            full_url,
+        )
+    except httpx.RequestError as e:
+        logger.warning(
+            "Failed to connect to Quraite backend at %s: %s",
+            quraite_endpoint,
+            e,
+        )
+    except Exception as e:
+        logger.warning("Unexpected error updating agent URL: %s", e)
+
+
+def create_app(
+    agent_adapter: BaseAdapter,
+    *,
+    agent_id: str | None = None,
+    tunnel_config: TunnelConfig | None = None,
+) -> FastAPI:
+    """
+    Create a standalone FastAPI app for an agent.
+
+    Returns a FastAPI application that developers can run with any ASGI server
+    (uvicorn, hypercorn, etc.). The app is self-contained with lifespan management.
+
+    Args:
+        agent_adapter: The agent adapter instance (must inherit from BaseAdapter)
+        agent_id: Optional Quraite platform agent ID for backend registration
+        tunnel_config: Optional TunnelConfig object. This is required if you are using a tunnel. To get the tunnel config, use the setup_tunnel function.
+
+    Returns:
+        FastAPI application instance with agent endpoints
+    """
+    logger.info("Creating FastAPI app with agent adapter")
+
+    adapter = agent_adapter
+
+    # Extract tunnel info
+    tunnel_obj = tunnel_config.tunnel_obj if tunnel_config else None
+    agent_url = tunnel_config.agent_url if tunnel_config else None
+    tunnel_type = tunnel_config.tunnel_type if tunnel_config else None
+
+    # Create lifespan with tunnel and backend registration
+    from contextlib import asynccontextmanager
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        # Startup
+        logger.info("Agent server started successfully")
+        path = "/v1/agents/completions"
+
+        # Register with Quraite backend if agent_id and tunnel provided
+        if agent_id and tunnel_type:
+            quraite_endpoint = os.getenv("QURAITE_ENDPOINT", "https://api.quraite.ai")
+            await _update_backend_agent_url(agent_id, agent_url, quraite_endpoint)
+
+        if tunnel_type:
+            logger.info(f"Agent publicly available at {agent_url}{path}")
+            if not agent_id:
+                logger.info(
+                    f"Add this URL to your agent in the Quraite platform: {agent_url}{path}"
+                )
+        elif agent_url:
+            logger.info(
+                f"Agent running locally at {agent_url}{path}. Use tunnel option to make it publicly available."
+            )
+
+        yield
+
+        # Shutdown - cleanup tunnel
+        if tunnel_obj and tunnel_type:
+            logger.info("Closing %s tunnel...", tunnel_type)
+            loop = asyncio.get_event_loop()
+            await loop.run_in_executor(None, _cleanup_tunnel, tunnel_obj, tunnel_type)
+
+    # Create FastAPI app with lifespan
+    app = FastAPI(title="Quraite Agent Server", lifespan=lifespan)
+
+    # Add CORS middleware
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Health check endpoint
+    @app.get("/")
+    def health_check():
+        """Health check endpoint."""
+        return {
+            "status": "ok",
+            "message": "Agent server is running",
+        }
+
+    # Agent invocation endpoint
+    @app.post("/v1/agents/completions", response_model=InvokeOutput)
+    async def invoke_agent(request: InvokeInput) -> InvokeOutput:
+        """
+        Agent invocation endpoint.
+
+        Args:
+            request: InvokeInput containing user_message and session_id
+
+        Returns:
+            InvokeOutput with agent response
+
+        Raises:
+            HTTPException: If agent invocation fails
+        """
+        try:
+            response = await adapter.ainvoke(input=request)
+            return response
+        except Exception as e:
+            logger.exception("Agent invocation failed")
+            raise HTTPException(
+                status_code=500,
+                detail=f"Agent invocation failed: {str(e)}",
+            ) from e
+
+    logger.info("FastAPI app created successfully")
+    return app
+
+
+def run_agent(
+    agent_adapter: BaseAdapter,
+    *,
+    agent_id: str | None = None,
+    port: int = 8080,
+    host: str = "0.0.0.0",
+    tunnel: Literal["none", "cloudflare", "ngrok"] = "none",
+) -> None:
+    """
+    Run an agent with a single line of code.
+
+    This function starts a FastAPI server for the provided agent adapter,
+    providing the best developer experience.
+
+    Args:
+        agent_adapter: The agent adapter instance (must inherit from BaseAdapter)
+        agent_id: Optional Quraite platform agent ID
+        port: Port number for the local server (default: 8080)
+        host: Host address (default: "0.0.0.0")
+        tunnel: Tunnel type ("none", "cloudflare", "ngrok") for public access
+
+    Example:
+        ```python
+        from quraite import run_agent
+        from quraite.adapters.langchain_adapter import LangchainAdapter
+
+        # Create adapter with tracing enabled
+        adapter = LangchainAdapter(agent_graph=my_graph, tracing=True)
+
+        # Run with tunnel
+        run_agent(adapter, tunnel="cloudflare", agent_id="agent-123")
+        ```
+    """
+    logger.info(
+        "Starting agent runner (port=%d, tunnel=%s, agent_id=%s)",
+        port,
+        tunnel,
+        agent_id,
+    )
+
+    # Setup tunnel if requested
+    tunnel_config = None
+    if tunnel != "none":
+        logger.info("Setting up %s tunnel on port %s...", tunnel, port)
+        tunnel_config = setup_tunnel(port, host, tunnel)
+
+    # Create app with tunnel config
+    app = create_app(agent_adapter, agent_id=agent_id, tunnel_config=tunnel_config)
+
+    # Run server
+    uvicorn.run(app, host=host, port=port)

quraite/tracing/__init__.py

@@ -1,8 +1,10 @@
 """Tracing infrastructure for OpenTelemetry span collection and processing."""
 
-from quraite.tracing.span_exporter import QuraiteInMemorySpanExporter
-from quraite.tracing.span_processor import QuraiteSimpleSpanProcessor
-from quraite.tracing.tool_extractors import Framework, ToolCallInfo, get_tool_extractor
+from quraite.constants.framework import Framework
+from quraite.tracing.setup import setup_tracing
+from quraite.tracing.span_exporter import QuraiteSpanExporter
+from quraite.tracing.span_processor import QuraiteSpanProcessor
+from quraite.tracing.tool_extractors import ToolCallInfo, get_tool_extractor
 from quraite.tracing.trace import AgentSpan, AgentTrace, CostInfo, TokenInfo
 from quraite.tracing.types import Event, Link, Resource, SpanContext, Status
 
@@ -15,11 +17,12 @@ __all__ = [
     "Tool",
     "ToolCallInfo",
     "get_tool_extractor",
-    "QuraiteInMemorySpanExporter",
-    "QuraiteSimpleSpanProcessor",
+    "QuraiteSpanExporter",
+    "QuraiteSpanProcessor",
     "Event",
     "Link",
     "Resource",
     "SpanContext",
     "Status",
+    "setup_tracing",
 ]

quraite/tracing/constants.py

@@ -1,15 +1 @@
-from enum import Enum
-
 QURAITE_TRACER_NAME = "quraite.instrumentation"
-
-
-class Framework(str, Enum):
-    """Supported agent frameworks."""
-
-    DEFAULT = "default"
-    PYDANTIC_AI = "pydantic_ai"
-    LANGCHAIN = "langchain"
-    GOOGLE_ADK = "google_adk"
-    OPENAI_AGENTS = "openai_agents"
-    AGNO = "agno"
-    SMOLAGENTS = "smolagents"

quraite/tracing/setup.py

@@ -0,0 +1,129 @@
+"""Centralized tracing setup and framework instrumentation."""
+
+
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider as SDKTracerProvider
+
+from quraite.constants.framework import Framework
+from quraite.logger import get_logger
+from quraite.tracing.span_exporter import QuraiteSpanExporter
+from quraite.tracing.span_processor import QuraiteSpanProcessor
+
+logger = get_logger(__name__)
+
+
+def setup_tracing(
+    frameworks: list[Framework | str] = [],
+    tracer_provider: SDKTracerProvider | None = None,
+) -> SDKTracerProvider:
+    """
+    Configure tracing once at app startup.
+
+    Args:
+        frameworks: Frameworks to instrument (e.g., [Framework.LANGCHAIN])
+        tracer_provider: Optional existing provider (auto-creates if None)
+
+    Returns:
+        Configured TracerProvider to pass to adapters
+    """
+    provider = tracer_provider or _create_tracer_provider()
+    _inject_quraite_processor(provider)
+
+    for framework in frameworks:
+        _instrument_framework(framework, provider)
+
+    logger.info("Tracing setup complete for frameworks: %s", frameworks)
+    return provider
+
+
+def _create_tracer_provider() -> SDKTracerProvider:
+    """Create TracerProvider or use existing global provider."""
+    global_provider = trace.get_tracer_provider()
+    if isinstance(global_provider, SDKTracerProvider):
+        logger.debug("Using existing global TracerProvider")
+        return global_provider
+
+    logger.debug("Creating new TracerProvider")
+    return SDKTracerProvider()
+
+
+def _inject_quraite_processor(provider: SDKTracerProvider) -> None:
+    """Inject QuraiteSpanProcessor if not already present."""
+    has_quraite_processor = any(
+        isinstance(processor, QuraiteSpanProcessor)
+        for processor in provider._active_span_processor._span_processors
+    )
+
+    if not has_quraite_processor:
+        logger.debug("Injecting QuraiteSpanProcessor")
+        exporter = QuraiteSpanExporter()
+        processor = QuraiteSpanProcessor(exporter)
+        provider.add_span_processor(processor)
+        logger.info("QuraiteSpanProcessor injected")
+    else:
+        logger.debug("QuraiteSpanProcessor already present")
+
+
+def _instrument_framework(framework: Framework | str, provider: SDKTracerProvider) -> None:
+    """Instrument a specific framework (idempotent)."""
+    framework_str = framework.value if isinstance(framework, Framework) else framework
+
+    try:
+        match framework_str:
+            case Framework.LANGCHAIN | "langchain":
+                from openinference.instrumentation.langchain import (
+                    LangChainInstrumentor,
+                )
+
+                LangChainInstrumentor().instrument(tracer_provider=provider)
+
+            case Framework.AGNO | "agno":
+                from openinference.instrumentation.agno import AgnoInstrumentor
+
+                AgnoInstrumentor().instrument(tracer_provider=provider)
+
+            case Framework.PYDANTIC_AI | "pydantic_ai":
+                from openinference.instrumentation.pydantic_ai import (
+                    OpenInferenceSpanProcessor,
+                )
+
+                # Pydantic AI instrumentation requires the tracer provider to be set globally
+                trace.set_tracer_provider(provider)
+                provider.add_span_processor(OpenInferenceSpanProcessor())
+
+            case Framework.GOOGLE_ADK | "google_adk":
+                from openinference.instrumentation.google_adk import (
+                    GoogleADKInstrumentor,
+                )
+
+                GoogleADKInstrumentor().instrument(tracer_provider=provider)
+
+            case Framework.SMOLAGENTS | "smolagents":
+                from openinference.instrumentation.smolagents import (
+                    SmolagentsInstrumentor,
+                )
+
+                SmolagentsInstrumentor().instrument(tracer_provider=provider)
+
+            case Framework.OPENAI_AGENTS | "openai_agents":
+                from openinference.instrumentation.openai_agents import (
+                    OpenAIAgentsInstrumentor,
+                )
+
+                OpenAIAgentsInstrumentor().instrument(tracer_provider=provider)
+            case Framework.OPENAI | "openai":
+                from openinference.instrumentation.openai import OpenAIInstrumentor
+
+                OpenAIInstrumentor().instrument(tracer_provider=provider)
+            case _:
+                logger.warning("Unknown framework: %s", framework_str)
+                return
+
+        logger.info("Instrumented framework: %s", framework_str)
+
+    except ImportError as e:
+        logger.warning(
+            "Failed to import instrumentor for %s: %s. Install the instrumentation package.",
+            framework_str,
+            e,
+        )

quraite/tracing/span_exporter.py

@@ -8,10 +8,10 @@ from opentelemetry.sdk.trace import ReadableSpan
 from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
 
 
-class QuraiteInMemorySpanExporter(SpanExporter):
+class QuraiteSpanExporter(SpanExporter):
     def __init__(self) -> None:
         # self.spans: typing.List[ReadableSpan] = []
-        self.traces: typing.Dict[int, typing.List[ReadableSpan]] = defaultdict(list)
+        self.traces: dict[int, list[ReadableSpan]] = defaultdict(list)
         self._stopped = False
         self._lock = threading.Lock()
 
@@ -28,7 +28,7 @@ class QuraiteInMemorySpanExporter(SpanExporter):
 
         return SpanExportResult.SUCCESS
 
-    def get_spans_by_trace_id(self, trace_id: int) -> typing.List[ReadableSpan]:
+    def get_spans_by_trace_id(self, trace_id: int) -> list[ReadableSpan]:
         """Get all spans for a specific trace ID"""
         return self.traces.get(trace_id, [])
 
@@ -43,11 +43,11 @@ class QuraiteInMemorySpanExporter(SpanExporter):
     def force_flush(self, timeout_millis: int = 30000) -> bool:
         return True
 
-    def get_traces(self) -> typing.Dict[int, typing.List[ReadableSpan]]:
+    def get_traces(self) -> dict[int, list[ReadableSpan]]:
         """Get all spans grouped by trace ID"""
         return dict(self.traces)
 
-    def get_trace(self, trace_id: int) -> typing.List[ReadableSpan]:
+    def get_trace(self, trace_id: int) -> list[ReadableSpan]:
         """Get all spans for a specific trace"""
         return self.traces.get(trace_id, [])
 
@@ -85,7 +85,7 @@ class QuraiteInMemorySpanExporter(SpanExporter):
         #             print(f"   {indent}   └─ Attributes: {dict(span.attributes)}")
         #     print()
 
-    def save_traces_to_file(self, filename: typing.Optional[str] = "traces.json"):
+    def save_traces_to_file(self, filename: str | None = "traces.json"):
         """Save a trace to a file"""
         traces = []
         for trace_id, spans in self.traces.items():