Docs

Reference

Release Notes

Chatbot SDK - Python Library

Python Library API

Method signatures, parameters, return types, and interfaces for using chatbotClient directly in Python code - no server process required.

from chatbot import chatbotClientPython 3.10+No HTTP server needed

Class

chatbotClient

The main entry point for the Python library. Instantiate once and reuse across multiple sessions. Thread-safe for concurrent use in async servers.

chatbotClient.__init__

chatbotClient(
  openai_api_key: str,
  storage: StorageBackend,
  form_config: FormConfig,
  pdf_filler: PDFFiller | None = None,
  prompt_builder: PromptBuilder | None = None,
  rate_limiter: RateLimiter | None = None,
)

Creates a new client instance. All required dependencies must be provided at construction time. The client validates configuration immediately and raises EnvironmentError if anything is missing.

ReturnschatbotClient

ParameterTypeRequired / DefaultDescription

openai_api_keystrrequiredOpenAI API key (sk-…). Used for every GPT-4o-mini extraction call.

storageStorageBackendrequiredStorage instance - LocalStorage or S3Storage (or custom implementation).

form_configFormConfigrequiredForm config loaded from configs/ directory via FormConfig.from_directory().

pdf_fillerPDFFiller | Noneopt / NonePDF filler instance. None disables PDF filling (data-only mode).

prompt_builderPromptBuilder | Noneopt / NoneCustom prompt builder. None uses the built-in default.

rate_limiterRateLimiter | Noneopt / NoneRate limiter instance. None disables rate limiting.

Method

send_message()

Process one conversation turn. Call with an empty string for the first turn to receive the greeting. Returns a 3-tuple - check complete before reading data.

chatbotClient.send_message

client.send_message(
  user_id: str,
  session_id: str,
  message: str,
  pdf_path: str | None = None,
) -> tuple[str, bool, dict | None]

Sends the investor's message through the state machine, runs GPT-4o-mini extraction if needed, advances the conversation state, and returns the bot's response. On the first call per session, pass an empty string to receive the greeting.

Returnstuple[str, bool, dict | None]

ParameterTypeRequired / DefaultDescription

user_idstrrequiredUnique identifier for the investor.

session_idstrrequiredUnique identifier for this session.

messagestrrequiredInvestor's message. Pass '' (empty) for the first turn.

pdf_pathstr | Noneopt / NoneOverride chatbot_PDF_PATH for this call.

Return value - tuple[str, bool, dict | None]

IndexTypeDescription

[0] responsestrBot's reply text for this turn.

[1] completeboolTrue when the session has reached COMPLETE state.

[2] datadict | NoneFlat dict of all collected fields. None until complete = True.

Method

get_fill_report_text()

chatbotClient.get_fill_report_text

client.get_fill_report_text(
  user_id: str,
  session_id: str,
) -> str

Returns a human-readable text summary of the fill report for a completed session - field counts, fill percentage, and a list of any skipped fields. Only valid after send_message() has returned complete = True.

Returnsstr

ParameterTypeRequired / DefaultDescription

user_idstrrequiredThe investor user ID.

session_idstrrequiredThe session ID.

Class

LocalStorage

Stores sessions as JSON files on the local filesystem. The data and config directories are created automatically on first use.

LocalStorage.__init__

LocalStorage(
  data_path: str = "./chatbot_data",
  config_path: str = "./configs",
)

Creates a local storage backend. data_path is where session files are written. config_path is where form config JSONs are read from.

ReturnsLocalStorage

Class

S3Storage

Stores sessions as S3 objects. Credentials are resolved from environment variables, AWS profile, or the instance metadata service (IAM role).

S3Storage.__init__

S3Storage(
  output_bucket: str,
  config_bucket: str,
  region: str = "us-east-1",
)

Creates an S3 storage backend. output_bucket is used for read/write of session data. config_bucket is read-only and holds your form config JSONs.

ReturnsS3Storage

Class

FormConfig

FormConfig.from_directory

FormConfig.from_directory(
  config_path: str,
) -> FormConfig

Class method. Loads all JSON config files from the given directory - form_keys.json, mandatory.json, meta_form_keys.json, field_questions.json, form_keys_label.json, and the global_investor_type_keys/ subdirectory. Raises FileNotFoundError if any required file is missing.

ReturnsFormConfig

Classes

PDF Filler Classes

Pass one of these to chatbotClient(pdf_filler=...) to enable PDF filling. Pass None (default) for data-only mode.

MapperPDFFiller.__init__

MapperPDFFiller(
  api_url: str = "http://localhost:8000",
  url_prefix: str = "/mapper",
  api_key: str | None = None,
)

Connects to the self-hosted mapper service. api_url is the base URL. url_prefix is /mapper for api_server.py or empty string for fastapi_app.py. api_key is optional - leave None if mapper has no auth.

ReturnsMapperPDFFiller

ManagedPDFFiller.__init__

ManagedPDFFiller(
  auth0_domain: str,
  client_id: str,
  client_secret: str,
  audience: str,
  lambda_url: str,
  api_key: str,
)

Connects to the private Auth0 + Lambda fill service. All six parameters are required. Requires the chatbot-managed package (not open source - contact your account team).

ReturnsManagedPDFFiller