outsail-sdk 0.28.1__tar.gz

outsail_sdk-0.28.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Atomic Shift
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

outsail_sdk-0.28.1/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: outsail-sdk
+Version: 0.28.1
+Summary: Python SDK for the Outsail Context Intelligence Platform
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/theatomicshift/outsail
+Project-URL: Repository, https://github.com/theatomicshift/outsail
+Keywords: outsail,context-intelligence,ai,research,agents
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# Outsail Python SDK
+
+`outsail-sdk` is the official async Python SDK for Outsail. It supports Python 3.10–3.13.
+
+```bash
+pip install outsail-sdk
+```
+
+```python
+import asyncio
+from outsail import OutsailClient, OutsailApiError
+
+async def main():
+    async with OutsailClient(api_key="osk_...") as client:
+        pack = await client.research("Research current OAuth migration guidance", profile="developer", discover=True)
+        print(pack.answer)
+
+asyncio.run(main())
+```
+
+For account-session authentication, call `await client.login(email, password)`, then construct a client with the returned session/API token. Production services should create scoped keys with `create_api_key()` and pass them as `api_key`; do not put keys in browser code.
+
+## Research and streaming
+
+Use `extract`, `map`, `discover`, `research`, `start_research`, `verify`, `compare`, `report`, and `decision_report` to build agent-ready workflows. `start_research` accepts the same full options as `research`, including provider, budget, cache, site, and Context Memory settings.
+
+```python
+job = await client.start_research("Compare database migration guides", discover=True, max_sources=12)
+async for event in client.stream_research(job):
+    print(event.event_type, event.data)
+
+report = await client.report(pack)
+```
+
+The SDK includes Context Packs, monitors (including RSS feeds), knowledge-base creation and ingestion, connectors, graph, memory, trust, workflows, API keys, organizations, notifications, billing, and self-service account controls.
+
+```python
+monitor = await client.create_monitor("Track release notes", rss_feeds=["https://example.com/feed.xml"])
+base = await client.create_knowledge_base(name="Engineering docs")
+await client.ingest_knowledge_base_documents(base["id"], [{"title": "Runbook", "content": "# Recovery"}])
+```
+
+## Connectors and platform controls
+
+```python
+github = await client.create_github_connector("Engineering docs", token=os.environ["GITHUB_TOKEN"])
+await client.sync_github("owner/repository", connector_id=github.id)
+print(await client.operations())
+```
+
+`create_notion_connector`, `create_google_drive_connector`, and `create_slack_connector` return connector records. Call the matching `begin_*_authorization` method and open its URL in a browser, then run `sync_notion`, `sync_google_drive`, or `sync_slack`. The client also exposes graph, memory, trust-policy, workflow, Context Pack feedback, notifications, and usage operations for durable agent workflows.
+
+## Errors and compatibility
+
+Non-2xx API responses raise `OutsailApiError` (`OutsailError` remains a compatible alias), with `status` and parsed `body`. Supply `idempotency_key` when retrying research or ingestion. The SDK is version-locked to Outsail `0.28.0`; consult the served [OpenAPI reference](https://outsail.theatomicshift.com/openapi.json) for request and response details.
+
+## Compatibility and deprecations
+
+Use the SDK release that matches the platform’s `0.28.x` release. Breaking changes require a new major release; deprecated operations are announced in release notes before removal. Store API keys only in server-side environment variables and revoke keys promptly if they may have been exposed.
+
+OAuth callbacks and inbound GitHub/Slack webhooks are browser/server integration flows, not SDK calls. Create a connector, open its returned authorization URL, then call its sync method.

outsail_sdk-0.28.1/README.md

@@ -0,0 +1,61 @@
+# Outsail Python SDK
+
+`outsail-sdk` is the official async Python SDK for Outsail. It supports Python 3.10–3.13.
+
+```bash
+pip install outsail-sdk
+```
+
+```python
+import asyncio
+from outsail import OutsailClient, OutsailApiError
+
+async def main():
+    async with OutsailClient(api_key="osk_...") as client:
+        pack = await client.research("Research current OAuth migration guidance", profile="developer", discover=True)
+        print(pack.answer)
+
+asyncio.run(main())
+```
+
+For account-session authentication, call `await client.login(email, password)`, then construct a client with the returned session/API token. Production services should create scoped keys with `create_api_key()` and pass them as `api_key`; do not put keys in browser code.
+
+## Research and streaming
+
+Use `extract`, `map`, `discover`, `research`, `start_research`, `verify`, `compare`, `report`, and `decision_report` to build agent-ready workflows. `start_research` accepts the same full options as `research`, including provider, budget, cache, site, and Context Memory settings.
+
+```python
+job = await client.start_research("Compare database migration guides", discover=True, max_sources=12)
+async for event in client.stream_research(job):
+    print(event.event_type, event.data)
+
+report = await client.report(pack)
+```
+
+The SDK includes Context Packs, monitors (including RSS feeds), knowledge-base creation and ingestion, connectors, graph, memory, trust, workflows, API keys, organizations, notifications, billing, and self-service account controls.
+
+```python
+monitor = await client.create_monitor("Track release notes", rss_feeds=["https://example.com/feed.xml"])
+base = await client.create_knowledge_base(name="Engineering docs")
+await client.ingest_knowledge_base_documents(base["id"], [{"title": "Runbook", "content": "# Recovery"}])
+```
+
+## Connectors and platform controls
+
+```python
+github = await client.create_github_connector("Engineering docs", token=os.environ["GITHUB_TOKEN"])
+await client.sync_github("owner/repository", connector_id=github.id)
+print(await client.operations())
+```
+
+`create_notion_connector`, `create_google_drive_connector`, and `create_slack_connector` return connector records. Call the matching `begin_*_authorization` method and open its URL in a browser, then run `sync_notion`, `sync_google_drive`, or `sync_slack`. The client also exposes graph, memory, trust-policy, workflow, Context Pack feedback, notifications, and usage operations for durable agent workflows.
+
+## Errors and compatibility
+
+Non-2xx API responses raise `OutsailApiError` (`OutsailError` remains a compatible alias), with `status` and parsed `body`. Supply `idempotency_key` when retrying research or ingestion. The SDK is version-locked to Outsail `0.28.0`; consult the served [OpenAPI reference](https://outsail.theatomicshift.com/openapi.json) for request and response details.
+
+## Compatibility and deprecations
+
+Use the SDK release that matches the platform’s `0.28.x` release. Breaking changes require a new major release; deprecated operations are announced in release notes before removal. Store API keys only in server-side environment variables and revoke keys promptly if they may have been exposed.
+
+OAuth callbacks and inbound GitHub/Slack webhooks are browser/server integration flows, not SDK calls. Create a connector, open its returned authorization URL, then call its sync method.

outsail_sdk-0.28.1/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "outsail-sdk"
+version = "0.28.1"
+description = "Python SDK for the Outsail Context Intelligence Platform"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["outsail", "context-intelligence", "ai", "research", "agents"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = ["httpx>=0.27.0"]
+optional-dependencies = {dev = ["build>=1.2", "pytest>=8.0", "pytest-asyncio>=0.24.0", "twine>=5.0"]}
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+filterwarnings = ["error"]
+
+[tool.setuptools.package-data]
+outsail = ["py.typed"]
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.urls]
+Homepage = "https://github.com/theatomicshift/outsail"
+Repository = "https://github.com/theatomicshift/outsail"

outsail_sdk-0.28.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

outsail_sdk-0.28.1/src/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_sdk-0.28.1/src/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}")