outsail-sdk 0.28.1__py3-none-any.whl

outsail/__init__.py

@@ -0,0 +1,30 @@
+"""Outsail Python SDK — Context Intelligence for AI agents.
+
+Usage::
+
+    import asyncio
+    from outsail import OutsailClient
+
+    async def main():
+        async with OutsailClient(api_key="osk_...") as client:
+            pack = await client.research(objective="Assess OAuth guidance", discover=True)
+            print(pack.answer)
+
+    asyncio.run(main())
+"""
+
+from .client import OutsailClient
+from .errors import OutsailApiError, OutsailError
+from .streaming import SseEvent, stream_events
+from . import agent_tools
+from . import types
+
+__all__ = [
+    "OutsailClient",
+    "OutsailError",
+    "OutsailApiError",
+    "SseEvent",
+    "stream_events",
+    "agent_tools",
+    "types",
+]

outsail/agent_tools.py

@@ -0,0 +1,212 @@
+"""
+OpenAI and Claude tool definitions generated from the Outsail Capability
+Registry.  These functions let you register Outsail capabilities as tools
+for OpenAI Responses / Chat Completions API and Claude Messages API.
+
+Usage (OpenAI)::
+
+    from outsail import OutsailClient
+    from outsail.agent_tools import create_openai_tools, execute_tool_call
+
+    async with OutsailClient(base_url="...", api_key="...") as client:
+        tools = await create_openai_tools(client)
+        # Pass tools to OpenAI: tools parameter
+        # When the model returns a tool call:
+        result = await execute_tool_call(client, tool_call.function.name, json.loads(tool_call.function.arguments))
+
+Usage (Claude)::
+
+    from outsail import OutsailClient
+    from outsail.agent_tools import create_claude_tools, execute_tool_call
+
+    async with OutsailClient(base_url="...", api_key="...") as client:
+        tools = await create_claude_tools(client)
+        # Pass tools to Claude: tools parameter
+        # When Claude uses a tool:
+        result = await execute_tool_call(client, tool_call.name, tool_call.input)
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from outsail.client import OutsailClient
+
+
+# ---------------------------------------------------------------------------
+# Tool definition generators
+# ---------------------------------------------------------------------------
+
+async def create_openai_tools(client: OutsailClient) -> list[dict]:
+    """Fetch OpenAI-compatible tool definitions from the Outsail server.
+
+    Tools are generated from the curated Capability Registry — only
+    agent-safe operations are included.
+
+    Args:
+        client: Authenticated OutsailClient instance.
+
+    Returns:
+        List of OpenAI function tool definitions.
+    """
+    response = await client._request("GET", "/developer/tools/openai")
+    return response.get("tools", [])
+
+
+async def create_claude_tools(client: OutsailClient) -> list[dict]:
+    """Fetch Claude-compatible tool definitions from the Outsail server.
+
+    Tools are generated from the curated Capability Registry — only
+    agent-safe operations are included.
+
+    Args:
+        client: Authenticated OutsailClient instance.
+
+    Returns:
+        List of Claude tool definitions.
+    """
+    response = await client._request("GET", "/developer/tools/claude")
+    return response.get("tools", [])
+
+
+# ---------------------------------------------------------------------------
+# Tool call executor
+# ---------------------------------------------------------------------------
+
+TOOL_HANDLERS: dict[str, callable] = {
+    # ── Research ────────────────────────────────────────────────────
+    "outsail_research_start": lambda client, args: client.start_research(
+        objective=args.get("objective", ""),
+        urls=args.get("urls"),
+        profile=args.get("profile"),
+        depth=args.get("depth"),
+        discover=args.get("discover"),
+        max_sources=args.get("max_sources"),
+    ),
+    "outsail_research_status": lambda client, args: client.get_research_job(args["id"]),
+
+    # ── Context Packs ───────────────────────────────────────────────
+    "outsail_context_pack_get": lambda client, args: client.get_context_pack(args["id"]),
+    "outsail_agent_context_get": lambda client, args: client.agent_context(
+        args["id"], profile=args.get("profile"),
+    ),
+
+    # ── Core Tools ──────────────────────────────────────────────────
+    "outsail_verify": lambda client, args: client.verify(
+        args["claim"],
+        urls=args.get("urls"),
+        discover=args.get("discover"),
+        profile=args.get("profile"),
+    ),
+    "outsail_extract": lambda client, args: client.extract(args["url"]),
+    "outsail_map": lambda client, args: client.map(
+        args["url"],
+        max_pages=args.get("max_pages"),
+        max_depth=args.get("max_depth"),
+    ),
+    "outsail_compare": lambda client, args: client.compare(
+        args["items"],
+        objective=args.get("objective"),
+        profile=args.get("profile"),
+        depth=args.get("depth"),
+        discover=args.get("discover"),
+    ),
+    "outsail_report": lambda client, args: client.report(args["context_pack"]),
+    "outsail_decision_report": lambda client, args: client.report(args["context_pack"]),
+    "outsail_discover": lambda client, args: client.discover(
+        args["query"],
+        profile=args.get("profile"),
+        providers=args.get("providers"),
+        limit=args.get("limit"),
+    ),
+
+    # ── Monitors ────────────────────────────────────────────────────
+    "outsail_monitor_list": lambda client, _args: client.list_monitors(),
+    "outsail_monitor_get": lambda client, args: client.get_monitor(args["id"]),
+    "outsail_monitor_create": lambda client, args: client.create_monitor(
+        objective=args.get("objective", ""),
+        urls=args.get("urls"),
+        rss_feeds=args.get("rss_feeds"),
+        profile=args.get("profile"),
+        interval_minutes=args.get("interval_minutes"),
+        materiality_threshold=args.get("materiality_threshold"),
+    ),
+    "outsail_monitor_run": lambda client, args: client.check_monitor(args["id"]),
+    "outsail_monitor_pause": lambda client, args: client.set_monitor_status(args["id"], "paused"),
+    "outsail_monitor_resume": lambda client, args: client.set_monitor_status(args["id"], "active"),
+}
+
+
+async def execute_tool_call(
+    client: OutsailClient,
+    tool_name: str,
+    args: dict[str, Any],
+) -> Any:
+    """Execute a tool call by name with validated arguments.
+
+    Determines the correct SDK method from the tool name, calls it,
+    and returns the result.  For long-running research tools, returns
+    a job handle — use ``poll_tool_result`` to wait for completion.
+
+    Args:
+        client: Authenticated OutsailClient instance.
+        tool_name: Tool name (e.g. ``"outsail_research_start"``).
+        args: Tool arguments (validated against registry schema).
+
+    Returns:
+        Tool execution result.
+
+    Raises:
+        ValueError: If the tool name is unknown.
+        OutsailApiError: If the API call fails.
+    """
+    handler = TOOL_HANDLERS.get(tool_name)
+    if handler is None:
+        raise ValueError(
+            f"Unknown tool: {tool_name}. "
+            "Available tools can be fetched via create_openai_tools() or create_claude_tools()."
+        )
+    return await handler(client, args)
+
+
+async def poll_tool_result(
+    client: OutsailClient,
+    job_id: str,
+    *,
+    poll_interval_ms: int = 2000,
+    timeout_ms: int = 300_000,
+) -> Any:
+    """Poll a research job until completion.
+
+    Args:
+        client: Authenticated OutsailClient instance.
+        job_id: Research job ID from :meth:`start_research` /
+                ``outsail_research_start``.
+        poll_interval_ms: Polling interval in milliseconds (default 2000).
+        timeout_ms: Maximum wait time in milliseconds (default 300000 = 5 min).
+
+    Returns:
+        Completed job result with ``context_pack`` if successful.
+
+    Raises:
+        TimeoutError: If the job does not complete within ``timeout_ms``.
+        RuntimeError: If the job fails.
+    """
+    start_time = asyncio.get_event_loop().time()
+    deadline = start_time + (timeout_ms / 1000)
+
+    while True:
+        now = asyncio.get_event_loop().time()
+        if now >= deadline:
+            raise TimeoutError(f"Research job {job_id} timed out after {timeout_ms}ms")
+
+        await asyncio.sleep(poll_interval_ms / 1000)
+
+        job = await client.get_research_job(job_id)
+
+        if job.status == "completed":
+            return job
+        if job.status == "failed":
+            error_msg = getattr(job, "error", None) or "Unknown error"
+            raise RuntimeError(f"Research job {job_id} failed: {error_msg}")