Python SDK overview

toothfairyai@latest…

The toothfairyai package exposes a single ToothFairyClient whose managers cover the whole platform. Each manager is one attribute on the client and is documented on its own page with field tables sourced from the API spec.

from toothfairyai import ToothFairyClient

client = ToothFairyClient(
    api_key=os.environ["TF_API_KEY"],
    workspace_id=os.environ["TF_WORKSPACE_ID"],
)

agent = client.agents.create(
    label="Support",
    mode="retriever",
    interpolation_string="You are a helpful assistant.",
    goals="Help customers",
    temperature=0.7,
    max_tokens=2000,
    max_history=10,
    top_k=10,
    doc_top_k=5,
)

See Authentication & routing for all configuration options and the three routing domains (core API, AI service, streaming).

Managers

Manager	Accessor	Domain
Agents	client.agents	API
Agent Functions	client.agent_functions	API
Alerts	client.alerts	API
Authorisations	client.authorisations	API
Benchmarks	client.benchmarks	API
Billing	client.billing	API
Channels	client.channels	API
Charting Settings	client.charting_settings	API
Chat	client.chat	API + AI
Connections	client.connections	API
Dictionary	client.dictionary	API
Documents	client.documents	API + AI
Embeddings	client.embeddings	AI
Embeddings Settings	client.embeddings_settings	API
Entities	client.entities	API
Fine-Tuning	client.finetuning	Fine-Tuning
Folders	client.folders	API
Hooks	client.hooks	API
Members	client.members	API
Prompts	client.prompts	API
Predictions	client.predictions	AI streaming
Request Logs	client.request_logs	API
Scheduled Jobs	client.scheduled_jobs	API
Secrets	client.secrets	API
Sites	client.sites	API
Streaming	client.streaming	AI streaming
Triggers	client.triggers	API

Streams is Node-only

The Streams manager (client.streams) is only available in the Node.js SDK. The Python SDK does not ship a streams manager.

Conventions

• Snake_case kwargs (the supported surface): manager methods accept Pythonic snake_case keyword arguments and convert them deterministically to the exact camelCase wire fields the API expects, using mappings generated from the backend validator (e.g. interpolation_string → interpolationString, authorisation_id → authorisationID, has_ner → hasNER, workspace_id → workspaceid). Each page's request field table shows the exact Python kwarg name to pass for every wire field — including irregular keys that do not follow the mechanical conversion. Passing camelCase directly still works but is deprecated: it emits a FutureWarning and normalizes to the same wire key, so it is never needed as a fallback. Unknown field names emit a warning and are forwarded to the API, which rejects fields it does not recognize.
• Finetuning exception: the /finetuning/* endpoints read snake_case directly (training_type, base_model, test_size, …); the SDK passes those through unchanged instead of converting them.
• Response models: responses are parsed into typed dataclasses (Agent, Chat, Document, …) where available; lists return a ListResponse with an items attribute.
• Derived methods (e.g. agents.get_by_mode, agents.search) delegate to another SDK call and perform no direct HTTP request; they are marked derived on their pages.
• Streaming managers (predictions, streaming) consume Server-Sent Events; see their pages for event/yield semantics.
• Errors: all failures raise subclasses of ToothFairyError; see Error handling.