custodian-labs 0.1.0

Minimal Python SDK for building and deploying chatbot apps

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

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

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

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

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

pip install -e .[dev]
pytest -q

How to Publish

1. Build wheel and sdist:

python -m pip install --upgrade build
python -m build

2. Install locally from built artifacts:

pip install dist/*.whl

3. Optional: publish to TestPyPI:

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

4. Optional: publish to PyPI:

python -m twine upload dist/*