Metadata-Version: 2.4
Name: custodian-labs
Version: 0.1.0
Summary: Minimal Python SDK for building and deploying chatbot apps
Author: CustodianLabs
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# custodian_labs

`custodian_labs` is a minimal Python SDK for building and deploying chatbot apps against a FastAPI backend.

Default backend URL: `http://127.0.0.1:8000/v1`

## Install

```bash
pip install custodian-labs
```

## Environment Variables

- `CUSTODIAN_SDK_BASE_URL` (optional)
- `CUSTODIAN_SDK_API_KEY` (required for all non-health calls)

Legacy compatibility:
- `AI_SDK_BASE_URL` still works as fallback
- `AI_SDK_API_KEY` still works as fallback

## Quickstart: Assistant Class Style

```python
from custodian_labs import Assistant

my_examples = [
    {"user": "What is 2+2?", "assistant": "4"},
    {"user": "Say hi", "assistant": "Hello!"},
]

assistant = Assistant(
    model="gpt-4o",
    system_prompt="You are a helpful assistant"
)
assistant.add_examples(my_examples)
assistant.add_data_source_file("knowledge.txt")  # optional RAG file upload
app = assistant.deploy()

reply = app.chat("Summarize the main topic in my file")
print(reply.response)
print(reply.retrieved_contexts)
print(reply.messages)
```

## Quickstart: Minimal Function Style

```python
from custodian_labs import create_assistant

my_examples = [
    {"user": "What is 2+2?", "assistant": "4"},
]

app = create_assistant(
    model="gpt-4o",
    prompt="You are a helpful assistant",
    examples=my_examples,
)

app.chat()  # interactive CLI mode
```

## Quickstart: Builder Style

```python
from custodian_labs import AssistantBuilder

my_examples = [
    {"user": "Who are you?", "assistant": "I am your assistant."},
]

app = (
    AssistantBuilder()
    .with_model("gpt-4o")
    .with_prompt("You are a helpful assistant")
    .with_examples(my_examples)
    .with_data_source_file("knowledge.txt")
    .deploy()
)

app.chat()
```

## API Notes

- `create_assistant()` deploys directly via `POST /apps/deploy`.
- `Assistant.deploy()` deploys via `POST /assistants/{assistant_id}/deploy` and returns an `App`.
- `App.chat(message)` returns a structured response with:
  - `response`
  - `retrieved_contexts`
  - `messages`
  - `raw_payload`
- `App.chat()` with no message enters interactive CLI mode.

## Error Handling

The SDK raises typed exceptions:

- `AuthenticationError` for 401/missing API key
- `NotFoundError` for 404
- `ValidationError` for 422
- `ServerError` for 5xx
- `APIConnectionError` for network errors

All exceptions include endpoint/status details and the backend payload where available.

## Running Tests

```bash
pip install -e .[dev]
pytest -q
```

## How to Publish

1. Build wheel and sdist:

```bash
python -m pip install --upgrade build
python -m build
```

2. Install locally from built artifacts:

```bash
pip install dist/*.whl
```

3. Optional: publish to TestPyPI:

```bash
python -m pip install --upgrade twine
python -m twine upload --repository testpypi dist/*
```

4. Optional: publish to PyPI:

```bash
python -m twine upload dist/*
```
