ravnar 0.0.2__py3-none-any.whl

_ravnar/__init__.py

@@ -0,0 +1,11 @@
+__all__ = ["__version__"]
+
+try:
+    from .version import __version__
+except ModuleNotFoundError:
+    import warnings
+
+    warnings.warn("ravnar was not properly installed!", stacklevel=2)
+    del warnings
+
+    __version__ = "UNKNOWN"

_ravnar/ag_ui_compatibilities.py

@@ -0,0 +1,391 @@
+"""This module exist in anticipation of the release of https://github.com/ag-ui-protocol/ag-ui/pull/1307"""
+
+__all__ = [
+    "AgentCapabilities",
+    "ExecutionCapabilities",
+    "HumanInTheLoopCapabilities",
+    "IdentityCapabilities",
+    "MultiAgentCapabilities",
+    "MultimodalCapabilities",
+    "MultimodalInputCapabilities",
+    "MultimodalOutputCapabilities",
+    "OutputCapabilities",
+    "ReasoningCapabilities",
+    "StateCapabilities",
+    "SubAgentInfo",
+    "ToolsCapabilities",
+    "TransportCapabilities",
+]
+
+from typing import Any
+
+from ag_ui.core.types import ConfiguredBaseModel, Tool
+from pydantic import Field
+
+
+class SubAgentInfo(ConfiguredBaseModel):
+    """Describes a sub-agent that can be invoked by a parent agent."""
+
+    name: str = Field(description="Unique name or identifier of the sub-agent.")
+    description: str | None = Field(
+        default=None,
+        description="What this sub-agent specializes in. Helps clients build agent selection UIs.",
+    )
+
+
+class IdentityCapabilities(ConfiguredBaseModel):
+    """Basic metadata about the agent.
+
+    Useful for discovery UIs, agent marketplaces, and debugging. Set these when you want clients to display agent
+    information or when multiple agents are available and users need to pick one.
+    """
+
+    name: str | None = Field(
+        default=None,
+        description="Human-readable name shown in UIs and agent selectors.",
+    )
+    type: str | None = Field(
+        default=None,
+        description='The framework or platform powering this agent (e.g., "langgraph", "mastra", "crewai").',
+    )
+    description: str | None = Field(
+        default=None,
+        description="What this agent does — helps users and routing logic decide when to use it.",
+    )
+    version: str | None = Field(
+        default=None,
+        description='Semantic version of the agent (e.g., "1.2.0"). Useful for compatibility checks.',
+    )
+    provider: str | None = Field(default=None, description="Organization or team that maintains this agent.")
+    documentation_url: str | None = Field(default=None, description="URL to the agent's documentation or homepage.")
+    metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Arbitrary key-value pairs for integration-specific identity info.",
+    )
+
+
+class TransportCapabilities(ConfiguredBaseModel):
+    """Declares which transport mechanisms the agent supports.
+
+    Clients use this to pick the best connection strategy. Only set flags to `True` for transports your agent actually
+    handles — omit or set `False` for unsupported ones.
+    """
+
+    streaming: bool | None = Field(
+        default=None,
+        description="Set `True` if the agent streams responses via SSE. Most agents enable this.",
+    )
+    websocket: bool | None = Field(
+        default=None,
+        description="Set `True` if the agent accepts persistent WebSocket connections.",
+    )
+    http_binary: bool | None = Field(
+        default=None,
+        description="Set `True` if the agent supports the AG-UI binary protocol (protobuf over HTTP).",
+    )
+    push_notifications: bool | None = Field(
+        default=None,
+        description="Set `True` if the agent can send async updates via webhooks after a run finishes.",
+    )
+    resumable: bool | None = Field(
+        default=None,
+        description="Set `True` if the agent supports resuming interrupted streams via sequence numbers.",
+    )
+
+
+class ToolsCapabilities(ConfiguredBaseModel):
+    """Tool calling capabilities.
+
+    Distinguishes between tools the agent itself provides (listed in `items`) and tools the client passes at runtime
+    via `RunAgentInput.tools`. Enable this when your agent can call functions, search the web, execute code, etc.
+    """
+
+    supported: bool | None = Field(
+        default=None,
+        description=(
+            "Set `True` if the agent can make tool calls at all. Set `False` to explicitly signal tool calling is "
+            "disabled even if items are present."
+        ),
+    )
+    items: list[Tool] = Field(
+        default_factory=list,
+        description=(
+            "The tools this agent provides on its own (full JSON Schema definitions). These are distinct from "
+            "client-provided tools passed in `RunAgentInput.tools`."
+        ),
+    )
+    parallel_calls: bool | None = Field(
+        default=None,
+        description="Set `True` if the agent can invoke multiple tools concurrently within a single step.",
+    )
+    client_provided: bool | None = Field(
+        default=None,
+        description="Set `True` if the agent accepts and uses tools provided by the client at runtime.",
+    )
+
+
+class OutputCapabilities(ConfiguredBaseModel):
+    """Output format support.
+
+    Enable `structured_output` when your agent can return responses conforming to a JSON schema, which is useful for
+    programmatic consumption.
+    """
+
+    structured_output: bool | None = Field(
+        default=None,
+        description="Set `True` if the agent can produce structured JSON output matching a provided schema.",
+    )
+    supported_mime_types: list[str] = Field(
+        default_factory=list,
+        description=(
+            'MIME types the agent can produce (e.g., `["text/plain", "application/json"]`). Omit if the agent only '
+            "produces plain text."
+        ),
+    )
+
+
+class StateCapabilities(ConfiguredBaseModel):
+    """State and memory management capabilities.
+
+    These tell the client how the agent handles shared state and whether conversation context persists across runs.
+    """
+
+    snapshots: bool | None = Field(
+        default=None,
+        description="Set `True` if the agent emits `STATE_SNAPSHOT` events (full state replacement).",
+    )
+    deltas: bool | None = Field(
+        default=None,
+        description="Set `True` if the agent emits `STATE_DELTA` events (JSON Patch incremental updates).",
+    )
+    memory: bool | None = Field(
+        default=None,
+        description=(
+            "Set `True` if the agent has long-term memory beyond the current thread (e.g., vector store, knowledge "
+            "base, or cross-session recall)."
+        ),
+    )
+    persistent_state: bool | None = Field(
+        default=None,
+        description=(
+            "Set `True` if state is preserved across multiple runs within the same thread. When `False`, state resets "
+            "on each run."
+        ),
+    )
+
+
+class MultiAgentCapabilities(ConfiguredBaseModel):
+    """Multi-agent coordination capabilities.
+
+    Enable these when your agent can orchestrate or hand off work to other agents.
+    """
+
+    supported: bool | None = Field(
+        default=None,
+        description="Set `True` if the agent participates in any form of multi-agent coordination.",
+    )
+    delegation: bool | None = Field(
+        default=None,
+        description="Set `True` if the agent can delegate subtasks to other agents while retaining control.",
+    )
+    handoffs: bool | None = Field(
+        default=None,
+        description="Set `True` if the agent can transfer the conversation entirely to another agent.",
+    )
+    sub_agents: list[SubAgentInfo] = Field(
+        default_factory=list,
+        description="List of sub-agents this agent can invoke. Helps clients build agent selection UIs.",
+    )
+
+
+class ReasoningCapabilities(ConfiguredBaseModel):
+    """Reasoning and thinking capabilities.
+
+    Enable these when your agent exposes its internal thought process (e.g., chain-of-thought, extended thinking).
+    """
+
+    supported: bool | None = Field(
+        default=None,
+        description="Set `True` if the agent produces reasoning/thinking tokens visible to the client.",
+    )
+    streaming: bool | None = Field(
+        default=None,
+        description="Set `True` if reasoning tokens are streamed incrementally (vs. returned all at once).",
+    )
+    encrypted: bool | None = Field(
+        default=None,
+        description=(
+            "Set `True` if reasoning content is encrypted (zero-data-retention mode). Clients should expect opaque "
+            "`encrypted_value` fields instead of readable content."
+        ),
+    )
+
+
+class MultimodalInputCapabilities(ConfiguredBaseModel):
+    """Modalities the agent can accept as input.
+
+    Clients use this to show/hide file upload buttons, audio recorders, image pickers, etc.
+    """
+
+    image: bool | None = Field(
+        default=None,
+        description="Set `True` if the agent can process image inputs (e.g., screenshots, photos).",
+    )
+    audio: bool | None = Field(
+        default=None,
+        description="Set `True` if the agent can process audio inputs (speech, recordings).",
+    )
+    video: bool | None = Field(default=None, description="Set `True` if the agent can process video inputs.")
+    pdf: bool | None = Field(default=None, description="Set `True` if the agent can process PDF documents.")
+    file: bool | None = Field(
+        default=None,
+        description="Set `True` if the agent can process arbitrary file uploads.",
+    )
+
+
+class MultimodalOutputCapabilities(ConfiguredBaseModel):
+    """Modalities the agent can produce as output.
+
+    Clients use this to anticipate rich content in the agent's response.
+    """
+
+    image: bool | None = Field(
+        default=None,
+        description="Set `True` if the agent can generate images as part of its response.",
+    )
+    audio: bool | None = Field(
+        default=None,
+        description="Set `True` if the agent can produce audio output (text-to-speech, audio files).",
+    )
+
+
+class MultimodalCapabilities(ConfiguredBaseModel):
+    """Multimodal input and output support.
+
+    Organized into `input` and `output` sub-objects so clients can independently query what the agent accepts versus
+    what it produces.
+    """
+
+    input: MultimodalInputCapabilities = Field(
+        default_factory=MultimodalInputCapabilities,
+        description="Modalities the agent can accept as input (images, audio, video, PDFs, files).",
+    )
+    output: MultimodalOutputCapabilities = Field(
+        default_factory=MultimodalOutputCapabilities,
+        description="Modalities the agent can produce as output (images, audio).",
+    )
+
+
+class ExecutionCapabilities(ConfiguredBaseModel):
+    """Execution control and limits.
+
+    Declare these so clients can set expectations about how long or how many steps an agent run might take.
+    """
+
+    code_execution: bool | None = Field(
+        default=None,
+        description="Set `True` if the agent can execute code (e.g., Python, JavaScript) during a run.",
+    )
+    sandboxed: bool | None = Field(
+        default=None,
+        description=(
+            "Set `True` if code execution happens in a sandboxed/isolated environment. Only meaningful when "
+            "`code_execution` is `True`."
+        ),
+    )
+    max_iterations: int | None = Field(
+        default=None,
+        description=(
+            "Maximum number of tool-call/reasoning iterations the agent will perform per run. Helps clients display"
+            "progress or set timeout expectations."
+        ),
+    )
+    max_execution_time: int | None = Field(
+        default=None,
+        description="Maximum wall-clock time (in milliseconds) the agent will run before timing out.",
+    )
+
+
+class HumanInTheLoopCapabilities(ConfiguredBaseModel):
+    """Human-in-the-loop interaction support.
+
+    Enable these when your agent can pause execution to request human input, approval, or feedback before continuing.
+    """
+
+    supported: bool | None = Field(
+        default=None,
+        description="Set `True` if the agent supports any form of human-in-the-loop interaction.",
+    )
+    approvals: bool | None = Field(
+        default=None,
+        description=(
+            "Set `True` if the agent can pause and request explicit approval before performing sensitive actions "
+            "(e.g., sending emails, deleting data)."
+        ),
+    )
+    interventions: bool | None = Field(
+        default=None,
+        description="Set `True` if the agent allows humans to intervene and modify its plan mid-execution.",
+    )
+    feedback: bool | None = Field(
+        default=None,
+        description=(
+            "Set `True` if the agent can incorporate user feedback (thumbs up/down, corrections) to improve its "
+            "behavior within the current session."
+        ),
+    )
+
+
+class AgentCapabilities(ConfiguredBaseModel):
+    """A categorized snapshot of an agent's current capabilities.
+
+    All fields are optional — agents only declare what they support. Omitted fields mean the capability is not declared
+    (unknown), not that it's unsupported.
+
+    The `custom` field is an escape hatch for integration-specific capabilities that don't fit into the standard
+    categories.
+    """
+
+    identity: IdentityCapabilities = Field(
+        default_factory=IdentityCapabilities, description="Agent identity and metadata."
+    )
+    transport: TransportCapabilities = Field(
+        default_factory=TransportCapabilities,
+        description="Supported transport mechanisms (SSE, WebSocket, binary, etc.).",
+    )
+    tools: ToolsCapabilities = Field(
+        default_factory=ToolsCapabilities,
+        description="Tools the agent provides and tool calling configuration.",
+    )
+    output: OutputCapabilities = Field(
+        default_factory=OutputCapabilities,
+        description="Output format support (structured output, MIME types).",
+    )
+    state: StateCapabilities = Field(
+        default_factory=StateCapabilities,
+        description="State and memory management (snapshots, deltas, persistence).",
+    )
+    multi_agent: MultiAgentCapabilities = Field(
+        default_factory=MultiAgentCapabilities,
+        description="Multi-agent coordination (delegation, handoffs, sub-agents).",
+    )
+    reasoning: ReasoningCapabilities = Field(
+        default_factory=ReasoningCapabilities,
+        description="Reasoning and thinking support (chain-of-thought, encrypted thinking).",
+    )
+    multi_modal: MultimodalCapabilities = Field(
+        default_factory=MultimodalCapabilities,
+        description="Multimodal input/output support (images, audio, video, files).",
+    )
+    execution: ExecutionCapabilities = Field(
+        default_factory=ExecutionCapabilities,
+        description="Execution control and limits (code execution, timeouts, iteration caps).",
+    )
+    human_in_the_loop: HumanInTheLoopCapabilities = Field(
+        default_factory=HumanInTheLoopCapabilities,
+        description="Human-in-the-loop support (approvals, interventions, feedback).",
+    )
+    custom: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Integration-specific capabilities not covered by the standard categories.",
+    )

_ravnar/agents.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import abc
+import textwrap
+import uuid
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING, Any
+
+import ag_ui.core
+import pydantic
+
+from _ravnar.ag_ui_compatibilities import AgentCapabilities, IdentityCapabilities, TransportCapabilities
+
+from .mixin import SetupTeardownMixin
+
+if TYPE_CHECKING:
+    import agno.agent
+    import pydantic_ai
+
+    from _ravnar.schema import QuickPrompt
+
+
+class Agent(abc.ABC, SetupTeardownMixin):
+    """Agent base class"""
+
+    @abc.abstractmethod
+    def run(self, input: ag_ui.core.RunAgentInput) -> AsyncIterator[ag_ui.core.Event]: ...
+
+    def get_capabilities(self) -> AgentCapabilities:
+        """The capabilities of the agent."""
+        return AgentCapabilities(transport=TransportCapabilities(streaming=True))
+
+    def get_quick_prompts(self) -> list[QuickPrompt]:
+        """The quick prompts of the agent."""
+        return []
+
+
+class DefaultAgent(Agent):
+    async def run(self, input: ag_ui.core.RunAgentInput) -> AsyncIterator[ag_ui.core.Event]:
+        message_id = str(uuid.uuid4())
+        message = """
+        Hello, I'm ravnar's default agent.
+        Unfortunately, I'm not terribly helpful right now.
+        """
+
+        yield ag_ui.core.RunStartedEvent(
+            thread_id=input.thread_id, run_id=input.run_id, parent_run_id=input.parent_run_id, input=input
+        )
+        yield ag_ui.core.TextMessageStartEvent(message_id=message_id)
+        for delta in textwrap.dedent(message.strip()).split():
+            yield ag_ui.core.TextMessageContentEvent(message_id=message_id, delta=delta)
+        yield ag_ui.core.TextMessageEndEvent(message_id=message_id)
+        yield ag_ui.core.RunFinishedEvent(thread_id=input.thread_id, run_id=input.run_id)
+
+
+class _AgentBase(Agent):
+    def __init__(
+        self,
+        *,
+        capabilities: AgentCapabilities | None = None,
+        quick_prompts: list[QuickPrompt] | None = None,
+    ):
+        if capabilities is None:
+            capabilities = super().get_capabilities()
+        self._capabilities = capabilities
+
+        if quick_prompts is None:
+            quick_prompts = super().get_quick_prompts()
+        self._quick_prompts = quick_prompts
+
+    def get_capabilities(self) -> AgentCapabilities:
+        """The capabilities of the agent."""
+        return self._capabilities
+
+    def get_quick_prompts(self) -> list[QuickPrompt]:
+        """The quick prompts of the agent."""
+        return self._quick_prompts
+
+
+class SSEAgent(_AgentBase):
+    """SSE Agent"""
+
+    def __init__(
+        self,
+        method: str,
+        url: str,
+        *,
+        client_kwargs: dict[str, Any] | None = None,
+        capabilities: AgentCapabilities | None = None,
+        quick_prompts: list[QuickPrompt] | None = None,
+    ):
+        self._method = method
+        self._url = url
+        if client_kwargs is None:
+            client_kwargs = {}
+        self._client_kwargs = client_kwargs
+
+        super().__init__(capabilities=capabilities, quick_prompts=quick_prompts)
+
+    async def run(self, input: ag_ui.core.RunAgentInput) -> AsyncIterator[ag_ui.core.Event]:
+        import httpx
+        import httpx_sse
+
+        async with (
+            httpx.AsyncClient() as client,
+            httpx_sse.aconnect_sse(
+                client,
+                self._method,
+                self._url,
+                json=input.model_dump(mode="json"),
+            ) as event_source,
+        ):
+            event_source.response.raise_for_status()
+
+            ta: pydantic.TypeAdapter[ag_ui.core.Event] = pydantic.TypeAdapter(ag_ui.core.Event)
+            async for sse in event_source.aiter_sse():
+                yield ta.validate_json(sse.data)
+
+
+class PydanticAiAgentWrapper(_AgentBase):
+    """Pydantic AI agent wrapper"""
+
+    def __init__(
+        self,
+        agent: pydantic_ai.Agent,
+        *,
+        identity: IdentityCapabilities | None = None,
+        quick_prompts: list[QuickPrompt] | None = None,
+    ) -> None:
+        self._agent = agent
+
+        if identity is None:
+            identity = IdentityCapabilities(name=agent.name)
+        capabilities = AgentCapabilities(identity=identity, transport=TransportCapabilities(streaming=True))
+
+        super().__init__(capabilities=capabilities, quick_prompts=quick_prompts)
+
+    def run(self, input: ag_ui.core.RunAgentInput) -> AsyncIterator[ag_ui.core.Event]:
+        from pydantic_ai.ui.ag_ui import AGUIAdapter
+
+        return AGUIAdapter(agent=self._agent, run_input=input, accept="text/event-stream").run_stream()  # type: ignore[return-value]
+
+
+class AgnoAgentWrapper(_AgentBase):
+    """Agno agent wrapper"""
+
+    def __init__(
+        self,
+        agent: agno.agent.Agent,
+        *,
+        identity: IdentityCapabilities | None = None,
+        quick_prompts: list[QuickPrompt] | None = None,
+    ) -> None:
+        self._agent = agent
+
+        if identity is None:
+            identity = IdentityCapabilities(name=agent.name)
+        capabilities = AgentCapabilities(identity=identity, transport=TransportCapabilities(streaming=True))
+
+        super().__init__(capabilities=capabilities, quick_prompts=quick_prompts)
+
+    def run(self, input: ag_ui.core.RunAgentInput) -> AsyncIterator[ag_ui.core.Event]:
+        from agno.os.interfaces.agui.router import run_agent
+
+        return run_agent(self._agent, input)  # type: ignore[return-value]

_ravnar/api/__init__.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+from fastapi import Depends
+
+from _ravnar import schema
+
+from .agents import make_router as make_agents_router
+from .threads import make_router as make_threads_router
+
+if TYPE_CHECKING:
+    from _ravnar.core import AgentHandler
+    from _ravnar.database import Database
+
+
+def make_router(
+    *, database: Database, agent_handler: AgentHandler, authenticated_user: Callable[..., Any]
+) -> schema.APIRouter:
+    router = schema.APIRouter(tags=["API"], dependencies=[Depends(authenticated_user)])
+
+    @router.get("/user")
+    async def get_user(
+        user: schema.User = Depends(authenticated_user),  # noqa: B008
+    ) -> schema.User:
+        return user
+
+    # FIXME: cache
+    @router.get("/config")
+    async def get_config() -> schema.APIConfig:
+        return schema.APIConfig(agents=agent_handler.configs)
+
+    router.include_router(
+        make_threads_router(database=database, agent_handler=agent_handler, authenticated_user=authenticated_user),
+        prefix="/threads",
+    )
+
+    router.include_router(
+        make_agents_router(agent_handler=agent_handler, authenticated_user=authenticated_user), prefix="/agents"
+    )
+
+    return router

_ravnar/api/agents.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Annotated, Any
+
+import ag_ui.core
+import ag_ui.encoder
+import fastsse
+from fastapi import Depends, Path
+
+from _ravnar import schema
+
+if TYPE_CHECKING:
+    from . import AgentHandler
+
+
+def make_router(*, agent_handler: AgentHandler, authenticated_user: Callable[..., Any]) -> schema.APIRouter:
+    router = schema.APIRouter(tags=["Agents"], dependencies=[Depends(authenticated_user)])
+
+    @router.sse("/{agentId}/run", methods=["POST"], response_model=schema.Event, tags=["Runs"])
+    async def create_stateless_run(
+        *, agent_id: Annotated[str, Path(alias="agentId")], run_agent_input: ag_ui.core.RunAgentInput
+    ) -> fastsse.Response:
+        return await agent_handler.run(agent_id, run_agent_input)
+
+    return router