Metadata-Version: 2.4
Name: capturedit
Version: 0.2.0
Summary: Official Python SDK for the CapturedIt Context Hub API
Project-URL: Homepage, https://capturedit.app
Project-URL: Documentation, https://capturedit.app/dashboard/integrations
License-Expression: MIT
Keywords: api,capturedit,context,httpx,sdk
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.22; extra == 'dev'
Description-Content-Type: text/markdown

# capturedit

Official Python SDK for the [CapturedIt](https://capturedit.app) Context Hub API.

## Install

```bash
pip install capturedit
```

## Quick start

```python
from capturedit import CapturedIt

client = CapturedIt(api_key="your_api_key")

# Search your library
results = client.search("machine learning")
for item in results.items:
    print(item.title)

# Get context for an AI prompt
context = client.get_context(q="project roadmap", format="text")

# Save a new item
result = client.create_item(
    "link",
    title="Interesting article",
    source_url="https://example.com/article",
)
print(f"Created item: {result.id}")

# Ask about a specific item
response = client.ask_about_item(result.id, question="Summarize this")
print(response.message)
```

## Async usage

```python
from capturedit import AsyncCapturedIt

async with AsyncCapturedIt(api_key="your_api_key") as client:
    results = await client.search("machine learning")
    for item in results.items:
        print(item.title)
```

## Configuration

```python
client = CapturedIt(
    api_key="your_api_key",
    base_url="https://api.capturedit.app",  # optional
    timeout=30.0,                            # optional, seconds
)
```

## Methods

| Method | Description |
|--------|-------------|
| `get_capabilities()` | Returns plan tier and feature flags |
| `search(query, *, limit, offset)` | Full-text search over your items |
| `get_context(*, limit, offset, q, format, include_conversations, max_chars)` | Recent or query-relevant items for AI context |
| `create_item(type, *, title, content_text, source_url, is_private)` | Create a new item |
| `capture_file(filename, mime_type, content_base64, *, ...)` | Upload a file (base64) |
| `get_item(item_id, *, include)` | Get a single item with enrichments |
| `delete_item(item_id)` | Delete an item |
| `transcribe(audio_base64, *, mime_type)` | Speech-to-text (max 20MB decoded audio) |
| `ask(question)` | Ask a question across your library (uses your plan's ask quota) |
| `ask_about_item(item_id, *, question, preset)` | Ask about a specific item |
| `list_conversations(item_id, *, limit, offset)` | Paginated conversation history |
| `delete_conversations(item_id)` | Clear conversation history for an item |

## Webhook verification

```python
from capturedit import verify_webhook_signature

is_valid = verify_webhook_signature(
    payload=request.body,
    header=request.headers["X-CapturedIt-Signature"],
    secret="your_webhook_secret",
)
```

## Error handling

```python
from capturedit import RateLimitError, AuthenticationError

try:
    results = client.search("query")
except RateLimitError as e:
    print(f"Retry after {e.retry_after} seconds")
except AuthenticationError:
    print("Invalid API key")
```

## Requirements

- Python 3.10+
- CapturedIt API key (create at Dashboard → Security)
- All plans can use the API from the app surfaces; a **Vault** plan unlocks full integrator access (`api_write`) and the context endpoint. `ask` is available on all plans within your monthly quota.

## Publishing (maintainers)

PyPI project name: **`capturedit`**.

1. **First release** (registers the project): from `packages/sdk-python` after tests:

   ```bash
   pip install build twine
   python -m build
   twine upload dist/*
   ```

   Use a [PyPI API token](https://pypi.org/manage/account/token/) with scope for this project.

2. **Ongoing CI**: In PyPI → **Publishing** → **Add a trusted publisher** → GitHub, point to this repository and workflow `.github/workflows/publish-sdk-pypi.yml`. Then use **Actions → Publish capturedit to PyPI** or push tag `sdk-python/v0.1.0` (match `pyproject.toml` version).

3. **Version bumps**: Edit `version` in `pyproject.toml` before each release.
