Metadata-Version: 2.5
Name: custodian-labs
Version: 0.2.4
Summary: Deploy AI agents with RAG, hosting and PII masking built in. Official Python SDK for Custodian Labs (API key required).
Project-URL: Homepage, https://custodianlabs.io
Project-URL: Documentation, https://docs.custodianlabs.io
Project-URL: Examples, https://github.com/Custodian-Labs/custodian-labs-python
Project-URL: Dashboard, https://dashboard.custodianlabs.io
Author: CustodianLabs
Keywords: ai-agents,chatbot,custodian-labs,llm,multi-agent,pii,privacy,rag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Custodian Labs Python SDK

**The fastest way to deploy AI agents with privacy built in.** Describe your agent in a few lines of Python. Custodian handles the RAG pipeline, hosting, conversation memory and PII masking, and gives you a live chat link to share.

- **Docs:** https://docs.custodianlabs.io
- **Examples:** https://github.com/Custodian-Labs/custodian-labs-python
- **Get an API key:** https://dashboard.custodianlabs.io

## Features

- **Deploy in a few lines:** one `deploy()` call gives you a hosted AI agent, an API, and a shareable chat page.
- **RAG built in:** add PDF, DOCX, XLSX, CSV or TXT files; parsing, chunking, embeddings and search are handled for you.
- **Privacy built in:** `privacy_enabled=True` masks names, phone numbers and other PII before the LLM sees them, and restores them in the reply.
- **Conversation memory:** follow-up questions keep their context automatically.
- **Multi-agent teams:** route questions to the right expert, or have agents work together in a workflow.
- **GuardianLayer:** mask PII in your own text and files (CSV, XLSX, DOCX, PDF, TXT).

## Install

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

Requires Python 3.10+.

## Set your API key

Get a key from the [Dashboard](https://dashboard.custodianlabs.io), then either put it in a `.env` file in your project folder:

```bash
CUSTODIAN_SDK_API_KEY=your-api-key
```

or set it in your terminal:

```bash
export CUSTODIAN_SDK_API_KEY="your-api-key"
```

In Google Colab or Jupyter, set it in a cell before using the SDK:

```python
import os
from getpass import getpass

os.environ["CUSTODIAN_SDK_API_KEY"] = getpass("Enter your Custodian Labs API key: ")
```

## Quickstart

```python
from custodian_labs import Custodian

ai_agent = Custodian(
    name="Contract Assistant",
    model="gpt-4o",
    system_prompt="Answer questions about the contract provided.",
)
ai_agent.add_data_source_file("contract.pdf")  # RAG over your own files

app = ai_agent.deploy()
print(app.chat_url)  # hosted chat page you can share

reply = app.chat("Who are the parties in this contract?")
print(reply.response)

app.chat()  # or chat interactively in your terminal
```

### Few-shot examples

Teach the agent your tone and format:

```python
ai_agent.add_examples([
    {"user": "How do I reset my password?", "assistant": "Go to Settings > Security > Reset password."},
])
```

### Builder style

```python
from custodian_labs import CustodianBuilder

app = (
    CustodianBuilder()
    .with_name("Support AI")
    .with_model("gpt-4o")
    .with_prompt("You are a helpful support agent.")
    .with_privacy()
    .deploy()
)
```

### Sharing

Links are public by default. Protect them with a password, or keep them private to your API key:

```python
app = ai_agent.deploy(share_mode="password", share_password="choose-a-password")
```

## Multi-agent teams

Several agents behind one app. Each keeps its own prompt and files.

```python
from custodian_labs import Custodian, CustodianSquad

car_specialist = Custodian(
    name="car_specialist",
    model="gpt-4o",
    system_prompt="Answer questions about the cars in the uploaded file.",
    topics=["car", "suv", "mpg", "maintenance"],
)
car_specialist.add_data_source_file("car_info.csv")

finance_advisor = Custodian(
    name="finance_advisor",
    model="gpt-4o",
    system_prompt="Explain loans, payments and running costs.",
    topics=["loan", "finance", "payment", "interest"],
)

team = CustodianSquad(
    name="Car Team",
    custodians=[car_specialist, finance_advisor],
    routing_mode="single",  # single | workflow | chain
)
app = team.deploy()

reply = app.chat("Which SUV has the lowest maintenance cost?")
print(reply.selected_agent, reply.response)
```

| Routing mode | Which agents answer |
|---|---|
| `single` | One agent: the one whose topics match the message |
| `workflow` | All agents in order; each answer is passed to the next |
| `chain` | Starts with the matching agent, then hands off to the agents it lists in `can_handoff_to` |

## GuardianLayer: mask PII in text and files

```python
from custodian_labs import GuardianLayer

guardian = GuardianLayer()

result = guardian.deidentify_text_outputs(
    "John Smith lives in Boston and his phone number is 617-555-0100.",
    masking_type="placeholder",  # redact | placeholder | transform
    pii_entities=["ALL"],
)
print(result.outputs[0].text)

masked = guardian.deidentify_file("customers.csv", masking_type="redact")
with open("masked_customers.csv", "wb") as f:
    f.write(masked.content)
```

## Plans

The Free plan includes 1 deployed agent and runs on `gpt-4o`. Pro adds more agents, multi-agent teams, more models and higher usage limits. See the [Dashboard](https://dashboard.custodianlabs.io) for current plans.

## Learn more

- Full documentation: https://docs.custodianlabs.io
- Runnable examples (RAG, few-shot, multi-agent routing, GuardianLayer, WebSocket): https://github.com/Custodian-Labs/custodian-labs-python
