Metadata-Version: 2.4
Name: contextfab
Version: 0.0.1
Summary: ContextFab SDK for Python
Author: ContextFab
License-Expression: Apache-2.0
Project-URL: Homepage, https://contextfab.ai
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.28.1
Requires-Dist: keyring<26,>=25.7.0
Requires-Dist: polars<2,>=1.39.3
Requires-Dist: PyJWT[crypto]<3,>=2.13.0
Dynamic: license-file

# ContextFab SDK for Python

Use the ContextFab SDK to connect Python applications and notebooks to ContextFab.

The current release provides access to governed datasets. You can list, load,
and save datasets from a local or hosted Python notebook.

## Install

Install the package from the Python package index:

```bash
pip install contextfab
```

## Use on your laptop

Start a blank marimo notebook with the SDK:

```bash
uvx --with contextfab marimo edit
```

Add this cell. Replace the API URL and dataset identifier with values from your tenant:

```python
import contextfab as cf

cf.connect("https://example.api.contextfab.ai")
datasets = cf.list_datasets()
df = cf.load_dataset("dataset-id")
df
```

When you develop this package from the repository, launch marimo with the local project:

```bash
uv run --project packages/public-sdk-py \
  --with "marimo>=0.23.16" \
  marimo edit --no-sandbox
```

For JupyterLab, run:

```bash
uv run --project packages/public-sdk-py \
  --with "jupyterlab>=4.4" \
  jupyter lab
```

For the local `demo` tenant, add the Caddy development certificate:

```python
from pathlib import Path

import contextfab as cf

local_ca = (
    Path.home()
    / "Library/Application Support/Caddy/pki/authorities/local/root.crt"
)
cf.connect("https://demo.api.localhost", ca_bundle=local_ca)
```

The SDK opens an Authorization Code + PKCE sign-in and keeps the refresh token
in the operating system credential store. It does not store the access token or
object-store credentials. Call `cf.logout()` to revoke the saved session.

The interactive token is restricted to the dataset API. It cannot call the
ContextFab GraphQL or MCP APIs. If a local identity stack is recreated, the SDK
replaces its stale public client registration once and restarts sign-in.

The SDK does not disable certificate checks. It does not send access tokens to signed artifact URLs. It does not collect telemetry.

## Use a hosted notebook

Hosted notebooks receive a session capability from the platform.
The module-level functions use it automatically:

```python
import contextfab as cf

available = cf.list_datasets()
df = cf.load_dataset(available[0].id)
saved = cf.save_dataset(df, "notebook-result")
```

`load_dataset()` always receives the canonical Parquet analysis artifact. The source dataset can use another storage format.

Saved datasets use the governed staging and commit path.
Each committed dataset is durable. Saving the same name again from the same
notebook creates a new immutable revision of the existing catalog dataset.

Do not copy the hosted capability outside its notebook session.
