Core Concepts

The SDK is built around three objects that map to the lifecycle of a deployed AI assistant.

Objects

Object	What it represents
Assistant	A configured AI assistant — system prompt, few-shot examples, and uploaded knowledge files
App	A deployed instance of an assistant that can receive chat messages
ChatSession	A stateful conversation thread on an App

Lifecycle

Assistant (configure)
    │
    ├── add_examples()       # optional few-shot examples
    ├── add_data_source_file() # optional RAG knowledge files
    │
    └── deploy()
            │
           App
            │
            ├── chat("message")   # single-turn or multi-turn
            └── session()         # ChatSession helper

An Assistant is a blueprint. Calling .deploy() produces an App — the live endpoint that handles chat. An App retains session state across calls, so multi-turn conversations work without you tracking history manually.

Data sources and RAG

When you upload a file to an Assistant (via .add_data_source_file()), the SDK parses and chunks the content into 800-character segments (with 120-character overlap), generates vector embeddings using OpenAI text-embedding-3-small, and indexes them for retrieval. At chat time, the API ranks chunks by cosine similarity to the user's query and injects the top matches into the LLM context automatically — no retrieval code needed on your side.

Supported file types: TXT, PDF, DOCX, XLS, XLSX.

PII masking

If the Assistant API is configured with PII_MASKING_ENABLED=true, Guardian Layer automatically de-identifies every chat message before it reaches the LLM. Sensitive tokens are replaced with [PII_n] placeholders, sent to the model, and restored in the response — so the LLM never sees the original values, but the user does.

This is transparent to the SDK — no code changes are needed on your side.

Three ways to build

Pattern	Best for
create_assistant()	One-shot deploy, fewest lines of code
AssistantBuilder	Fluent chain, readable config
Assistant class	Full control, reuse across deploys

All three patterns produce an App. See the individual pages for details.