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.
