Metadata-Version: 2.4
Name: periplus-python-sdk
Version: 0.11.0
Summary: Typed Periplus platform client with SQL and notebook integration
License-Expression: AGPL-3.0-only
Project-URL: Repository, https://github.com/elei-io/periplus
Project-URL: Issues, https://github.com/elei-io/periplus/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: licensing/LICENSE
License-File: licensing/NOTICE
License-File: licensing/README.md
License-File: licensing/THIRD_PARTY_NOTICES.md
Requires-Dist: httpx>=0.28
Requires-Dist: pydantic<3,>=2.12
Requires-Dist: sqlalchemy<3,>=2.0
Provides-Extra: notebook
Requires-Dist: marimo[sql]>=0.24.1; extra == "notebook"
Dynamic: license-file

# Periplus Python SDK

Typed organization operations and SQL access through the Periplus HTTP API.
The 0.11.0 platform interface requires the matching API release. It includes
the source-snapshot metadata introduced in 0.10.0 alongside customer operations.
Install from PyPI:

```sh
python -m pip install --upgrade periplus-python-sdk
```

```python
from periplus_sdk import Client

with Client("https://api.periplus.dev", api_key="ppl_…") as client:
    result = client.execute(
        "SELECT capture_id, url FROM public_v1.captures LIMIT ?", [10]
    )
    print(result.columns, result.rows)
```

The default origin is `https://api.periplus.dev`. Use `PERIPLUS_API_URL` to override it and `PERIPLUS_API_KEY` to
supply your personal organization API key. A key with `organization:sql:exec`
is required. Database usernames/passwords and anonymous access are not supported.
Use HTTPS outside loopback development. Connect directly to the API origin,
not the public marketing site.

Version 0.9.0 requires personal API keys instead of database credentials. Create
a key in the app's Settings → My API keys. It inherits your current access in
that organization; SQL requires your membership to have `organization:sql:exec`.
For local development, install `./clients/periplus-python-sdk` from the repository
root and connect to `http://localhost:8000`.

`AsyncClient` accepts the same options. `prepare` explains a SELECT; `execute`
returns typed columns/rows for read-only queries. `schema()` returns
visible tables, column types/descriptions and helper documentation. All SQL uses
`POST /api/v1/sql`; schema discovery uses `GET /api/v1/schema`. ClickHouse enforces
permissions. The SDK never retries automatically, including failed queries.

Public HTML joins use `parse_id` and `node_index`; `document_id` identifies exact
raw bytes. Public shorthand uses the `public_v1` schema.

In 0.10.0, `result.source_snapshot` is a typed `SourceSnapshot` containing
`layout_id` (UUID) and `publication_epoch` (integer), or `None` when no build-bound
public corpus was read. Buffered, asynchronous, streamed and DB-API results share
this contract. Compare both fields, not just the epoch. The identity describes
the public corpus inputs, not any native staff/external inputs. It does not retain
the data or request historical reads. This replaces the old nullable integer field;
use this SDK version with the corresponding API release.

For notebook/SQLAlchemy integration:

```python
from periplus_sdk import sql_api
from sqlalchemy import text

engine = sql_api.create_engine(base_url="http://localhost:8000", api_key="ppl_…")
with engine.connect() as connection:
    print(connection.execute(text("SELECT url FROM public_v1.captures LIMIT 5")).all())
engine.dispose()
```

Marimo discovers accessible tables, views, typed columns and comments through the
schema endpoint. Reflection does not execute SQL. One SQLAlchemy Inspector caches
its metadata; call `inspector.clear_cache()` to refresh it. Missing metadata raises
an error rather than presenting an apparently complete empty schema.

The DB-API connection advertises the ClickHouse dialect and converts native
nullable integer, decimal, date and datetime types. Nested types retain JSON wire
values. Writes are not exposed through the query API. There are no client
transactions; each statement is independent.
Streaming cursors expose incomplete/truncated results explicitly; configure
`allow_partial` only when partial results suit the application.

See [the public schema](../../docs/SCHEMA.md) and [query boundary](../../docs/QUERY.md).

## Organization resources

The same key selects your organization and inherits your live membership access.
`Client` and `AsyncClient` expose the same namespaces:

| Namespace | Operations |
| --- | --- |
| `identity`, `availability` | `get` |
| `discovery` | `create`, `get`, `list`, `iter`, `arrivals`, `cancel` |
| `retention`, `monitoring` | `create`, `preview`, `activate`, `get`, `list`, `iter`, `members`, `update`, `pause`, `resume`, `delete` |
| `saved_queries` | `create`, `get`, `list`, `iter`, `rename`, `delete` |
| `members` | `list`, `update_role`, `remove` |
| `invitations` | `list`, `create`, `cancel` |
| `api_keys` | `create`, `list`, `iter`, `revoke` |
| `usage` | `get` |
| `query_history` | `list`, `iter`, `get`, `summary` |
| `audit` | `list`, `iter` |

```python
from periplus_sdk import Client

with Client() as client:
    preview = client.retention.preview(
        name="Research sources", days=90,
        sql="SELECT capture_id FROM captures WHERE domain(url) = ?",
        parameters=["example.com"],
    )
    print(preview.id, preview.capture_count, preview.sample)
    # Review the selection before calling:
    # active = client.retention.activate(preview)
```

SQL previews persist inactive, frozen selections; activation never reruns SQL.
Explicit IDs/URLs passed to `create` activate immediately. Monitoring URLs must
already be known in the corpus. Use `members` and its `next_cursor` for complete
membership: policy detail contains a sample. Updates/deletion accept a fetched
`Policy` or an ID with `expected_version`; conflicts are never retried.

Paginated lists return `Page[T]` (`items`, `next_cursor`). Pass cursors unchanged
or use `iter()`; membership/invitation lists are bounded snapshots instead.
Offset-based lists can shift during concurrent changes. Query history and arrivals
use keyset cursors. UTC usage ranges have an exclusive end date, at most 93 days.
Query history is best-effort and expires after 30 days; it is not a billing ledger.

`ApiError` includes HTTP status, code, optional request ID, validation fields and
Retry-After seconds. `TransportError` means the outcome of a write can be unknown.
Keep creation IDs to reconcile; never blindly retry. Key creation is one-time:
`created.secret.get_secret_value()` reveals the secret and must only be used for
secure storage. Its ordinary representation is masked. Lost secrets cannot be
recovered.

For async streaming, use `async with await client.stream(sql) as stream` followed
by `async for batch in stream`. Streams validate completion and close on early
exit, errors, and cancellation. No threads or background polling are introduced.
