Jazzmine
OverviewReactSDKCoreLoggingSecurity
Builder

Builder: Configuration Models

The Builder Configuration Models module defines strongly typed dataclasses used by AgentBuilder.

Instead of passing one large, weakly typed dictionary, Jazzmine uses focused configuration classes grouped by concern:

  • Storage
  • LLM providers
  • Embeddings and memory
  • Sandbox execution
  • Agent behavior tuning
  • Security
  • HTTP server

All of these objects are consumed and validated by AgentBuilder before runtime resources are created.

Full Coverage Index

This section is the authoritative checklist for config coverage in this document.

2.1 Config Classes

ClassCategoryUsed by
JsonStorageStorageAgentBuilder.storage(...)
PostgresStorageStorageAgentBuilder.storage(...)
MongoDBStorageStorageAgentBuilder.storage(...)
OpenAILLMConfigLLMAgentBuilder.llm(...), AgentBuilder.script_gen_llm(...)
AnthropicLLMConfigLLMAgentBuilder.llm(...), AgentBuilder.script_gen_llm(...)
GeminiLLMConfigLLMAgentBuilder.llm(...), AgentBuilder.script_gen_llm(...)
AzureLLMConfigLLMAgentBuilder.llm(...), AgentBuilder.script_gen_llm(...)
CohereLLMConfigLLMAgentBuilder.llm(...), AgentBuilder.script_gen_llm(...)
BedrockLLMConfigLLMAgentBuilder.llm(...), AgentBuilder.script_gen_llm(...)
LocalLLMConfigLLMAgentBuilder.llm(...), AgentBuilder.script_gen_llm(...)
EmbeddingConfigEmbedding exportAgentBuilder.embeddings(...)
MemoryConfigMemory/QdrantAgentBuilder.memory(...)
FileMountSandbox mount helperSandboxSpec.file_mounts
SandboxSpecSandbox runtimeAgentBuilder.sandbox(...)
AgentSettingsRuntime tuningAgentBuilder.settings(...)
SecurityConfigSecurity guardAgentBuilder.security(...)
CORSConfigHTTP server CORSServerConfig.cors
ServerConfigHTTP serverAgentBuilder.server(...)
AliasDefinition
StorageConfigJsonStorage | PostgresStorage | MongoDBStorage
LLMConfigOpenAILLMConfig | AnthropicLLMConfig | GeminiLLMConfig | AzureLLMConfig | CohereLLMConfig | BedrockLLMConfig | LocalLLMConfig
DomainTermtuple[str, str, str, list[str], str]

Storage Configuration Classes

3.1 JsonStorage

File-backed storage for development and low-volume usage.

ParameterTypeDefaultDescription
pathstr""JSON path. Empty string means auto temp file created by builder.

3.2 PostgresStorage

PostgreSQL message/trace storage.

ParameterTypeDefaultDescription
dsnstrRequiredPostgreSQL DSN (example: postgresql://user:pass@host:5432/dbname).
pool_minint2Minimum asyncpg pool size.
pool_maxint10Maximum asyncpg pool size.

3.3 MongoDBStorage

MongoDB message/trace storage.

ParameterTypeDefaultDescription
uristrRequiredMongoDB URI (example: mongodb://user:pass@host:27017).
dbstr"jazzmine"Database name.

LLM Configuration Classes

All LLM classes are part of the LLMConfig union.

4.1 OpenAILLMConfig

OpenAI-compatible providers (OpenAI, vLLM, Ollama, Groq-style compatible endpoints, etc.).

ParameterTypeDefaultDescription
modelstrRequiredModel identifier.
api_keystrRequiredAPI key (Bearer token style).
base_urlstrRequiredBase URL of provider API.
temperaturefloat0.5Sampling temperature.
max_tokensint1024Max output tokens.
timeoutfloat90.0Request timeout in seconds.
top_pfloat | NoneNoneNucleus sampling parameter.
chat_endpointstr"/v1/chat/completions"Chat endpoint path.

4.2 AnthropicLLMConfig

Anthropic Claude provider.

ParameterTypeDefaultDescription
modelstrRequiredClaude model ID.
api_keystrRequiredAnthropic API key.
base_urlstr"https://api.anthropic.com"API base URL.
temperaturefloat0.5Sampling temperature.
max_tokensint1024Max output tokens.
timeoutfloat90.0Request timeout in seconds.

4.3 GeminiLLMConfig

Google Gemini provider via Generative Language API.

ParameterTypeDefaultDescription
modelstrRequiredGemini model ID.
api_keystrRequiredGoogle API key.
base_urlstr"https://generativelanguage.googleapis.com"API base URL.
temperaturefloat0.5Sampling temperature.
max_tokensint1024Max output tokens.
timeoutfloat90.0Request timeout in seconds.

4.4 AzureLLMConfig

Azure OpenAI deployment config.

ParameterTypeDefaultDescription
api_keystrRequiredAzure key.
endpointstrRequiredAzure resource endpoint URL.
deployment_namestrRequiredAzure deployment name.
api_versionstr"2024-02-15-preview"API version string.
temperaturefloat0.5Sampling temperature.
max_tokensint1024Max output tokens.
timeoutfloat90.0Request timeout in seconds.

4.5 CohereLLMConfig

Cohere Command provider config.

ParameterTypeDefaultDescription
api_keystrRequiredCohere API key.
modelstr"command-r-plus"Cohere model ID.
temperaturefloat0.5Sampling temperature.
max_tokensint1024Max output tokens.
timeoutfloat90.0Request timeout in seconds.

4.6 BedrockLLMConfig

AWS Bedrock model config.

ParameterTypeDefaultDescription
modelstrRequiredBedrock model ID.
region_namestrRequiredAWS region name.
temperaturefloat0.5Sampling temperature.
max_tokensint1024Max output tokens.
timeoutfloat90.0Kept for API consistency.

4.7 LocalLLMConfig

Local subprocess model config.

ParameterTypeDefaultDescription
binary_pathstrRequiredExecutable path. Must support -p "<prompt>" mode.
modelstr"local"Telemetry label.
temperaturefloat0.5Sampling temperature.
max_tokensint1024Max output tokens.
timeoutfloat90.0Informational in local mode.

Embedding and Memory Configuration Classes

5.1 EmbeddingConfig

Automatic local embedding export and tokenizer setup.

ParameterTypeDefaultDescription
model_idstr"BAAI/bge-small-en-v1.5"Hugging Face model ID.
output_dirstr""Output directory (empty means default under ~/.jazzmine/models).
tokenizer_onlyboolFalseOnly export tokenizer, skip ONNX model export.
quantizedboolTrueExport quantized ONNX model.
opsetint17ONNX opset.
force_rebuildboolFalseForce re-download/re-export.

5.2 MemoryConfig

Qdrant and embedding backend runtime configuration.

5.2.1 Qdrant Connectivity

ParameterTypeDefaultDescription
qdrant_urlstrRequiredQdrant URL.
tokenizer_pathstr""Tokenizer path (auto-resolved when embeddings() is used).
collection_prefixstr"jazzmine"Collection prefix.
qdrant_api_keystr | NoneNoneQdrant API key.
qdrant_auto_startboolTrueAuto-start local Qdrant container when relevant.
qdrant_docker_imagestr"qdrant/qdrant"Docker image for auto-start mode.
qdrant_container_namestr | NoneNoneOptional container name override.
qdrant_http_host_portint | NoneNoneHTTP host port override.
qdrant_data_volumestr"jazzmine-qdrant-data"Docker volume for Qdrant data.
qdrant_stop_on_shutdownboolTrueStop auto-started Qdrant on teardown.

5.2.2 Vector and Index Tuning

ParameterTypeDefaultDescription
vector_sizeint384Embedding vector size.
distance_metricstr"cosine"Similarity metric.
use_indexingboolTrueEnable ANN indexing.
quantizationint | None8Vector quantization bits (None, 4, or 8).
on_diskboolFalseStore vectors on disk.
replication_factorint1Replica count.
shard_numberint1Shard count.
indexing_thresholdint2000Segment indexing threshold.
flush_interval_secint15Flush interval.
max_optimization_threadsint1Optimization thread count.
use_sparse_vectorsboolTrueEnable sparse vectors for hybrid retrieval.

5.2.3 Local Embedding Backend Fields

ParameterTypeDefaultDescription
model_dirstr | NoneNoneLocal ONNX model directory.
quantizedboolFalseWhether local model is quantized.
max_batchint8Local embedding batch size.

5.2.4 Remote Embedding Backend Fields

ParameterTypeDefaultDescription
embed_providerstr"openai"Remote embed provider identifier.
embed_api_keystr | NoneNoneRemote API key.
embed_base_urlstr | NoneNoneRemote base URL override.
embed_model_namestr | NoneNoneRemote model name override.

Sandbox and Runtime Configuration Classes

6.1 FileMount

Host path mapping helper used by SandboxSpec.file_mounts.

ParameterTypeDefaultDescription
host_pathstrRequiredHost filesystem path.
container_pathstrRequiredPath mounted inside sandbox container.
read_onlyboolTrueRead-only mount toggle.
docker_host_pathstr | NoneNoneDocker host path override for DooD scenarios.

6.2 SandboxSpec

Sandbox execution environment specification.

6.2.1 Identity and Runtime

ParameterTypeDefaultDescription
namestrRequiredSandbox identifier.
python_versionstr"3.11"Base Python version for sandbox image.
execution_modestr"plan"Default mode: plan or interactive.

6.2.2 Resource Limits

ParameterTypeDefaultDescription
cpu_quotafloat0.5CPU quota.
memory_mbint256Memory cap in MB.
memory_swap_mbint-1Swap cap (-1 for unlimited).
pids_limitint64Max process/thread count.
timeout_secint30Execution timeout.
max_output_bytesint1048576Output cap.

6.2.3 Pool and Storage

ParameterTypeDefaultDescription
scratch_size_mbint128Scratch filesystem size in MB.
pool_sizeint1Warm container count.
pool_max_overflowint10Overflow container allowance.
pool_host_path_mapdict[str, str]{}Prefix map for host-path translation in DooD setups.

6.2.4 Network and Mounts

ParameterTypeDefaultDescription
allowed_hostslist[str][]Egress host allowlist.
allowed_portsdict[str, list[int]]{}Per-host allowed ports.
default_portint443Default port when no per-host override exists.
file_mountslist[FileMount][]Bind mounts.
pip_packageslist[str][]Packages baked into sandbox image.
secretsdict[str, str]{}Runtime environment secrets.

6.3 AgentSettings

High-level behavior tuning for the runtime pipeline.

ParameterTypeDefaultDescription
default_sandbox_namestr""Default sandbox fallback.
default_execution_modestr"plan"Default execution mode fallback.
max_task_calls_per_turnint4Max tool task calls per turn.
max_interactive_stepsint4Max interactive steps.
max_retriesint3Script generation retry count.
episodic_same_conv_limitint3Same-conversation episodic recall limit.
episodic_prev_conv_limitint1Previous-conversation episodic recall limit.
semantic_top_kint4Semantic term recall limit.
enhancer_history_windowint8Message enhancer history window.
summarizer_triggerint3Unsummarized threshold before summarizer runs.
max_episode_sizeint20Max episode size.
min_episode_sizeint2Min episode size.
episode_overlapint1Episode overlap count.
flow_top_kint3Flow candidate recall limit.
flow_rrf_kint10RRF k for flow ranking.
pool_max_overflowint10Global pool overflow cap.
pool_host_path_mapdict[str, str]{}Global host path map for pool path translation.

Security and Server Configuration Classes

7.1 SecurityConfig

Security guard injection and policy thresholds.

ParameterTypeDefaultDescription
input_moderatorAny | NoneNoneInput moderator instance.
toxicity_detectorAny | NoneNoneToxicity detector instance.
output_moderatorAny | NoneNoneOutput moderator instance.
file_sanitizerAny | NoneNoneFile sanitizer instance.
input_confidence_thresholdfloat0.5Input block threshold.
output_confidence_thresholdfloat0.5Output block threshold.
input_block_messagestrlong defaultMessage shown on input block.
output_block_messagestrlong defaultMessage shown on output block.
moderation_timeoutfloat10.0Timeout per moderation call.
fail_openboolTrueTimeout/exception behavior.

7.2 CORSConfig

CORS policy model used inside ServerConfig.

ParameterTypeDefaultDescription
originslist[str]["*"]Allowed origins.
allow_credentialsboolFalseAllow credentials in CORS.
allow_methodslist[str]["*"]Allowed HTTP methods.
allow_headerslist[str]["*"]Allowed request headers.
expose_headerslist[str][]Exposed response headers.
max_ageint600Preflight cache seconds.

7.3 ServerConfig

HTTP server behavior for builder-managed API server.

7.3.1 Network and Endpoints

ParameterTypeDefaultDescription
hoststr"0.0.0.0"Bind host.
portint1453Bind port.
chat_endpointstr"/chat"Chat endpoint path.
conversations_endpointstr"/conversations"Conversations endpoint base path.
health_endpointstr"/health"Health endpoint path.
info_endpointstr"/info"Info endpoint path.

7.3.2 Auth, Limits, and Metadata

ParameterTypeDefaultDescription
api_keystr | NoneNoneBearer auth key when enabled.
request_timeoutfloat120.0Request timeout seconds.
max_message_lengthint32768Maximum message length.
titlestr"Jazzmine Agent API"API title.
descriptionstr""API description.
api_versionstr"1.0.0"API version string.
docs_urlstr | None"/docs"Swagger URL (None disables).
redoc_urlstr | NoneNoneReDoc URL.

7.3.3 CORS, TLS, and Tuning

ParameterTypeDefaultDescription
corsCORSConfigCORSConfig()CORS policy object.
ssl_certfilestr | NoneNoneSSL certificate file path.
ssl_keyfilestr | NoneNoneSSL private key file path.
log_levelstr"info"Uvicorn log level.
backlogint2048Socket backlog size.
limit_concurrencyint | NoneNoneMax concurrent requests.
timeout_keep_aliveint5Keep-alive timeout seconds.

Validation, Defaults, and Practical Notes

  • These config objects are dataclasses and do not perform full runtime validation by themselves.
  • AgentBuilder._validate() is the central validation step before build-time I/O.
  • Use defaults first, then override only what you need for your deployment.
  • For production: explicitly set storage backend, API keys, sandbox limits, and server auth settings.

Numbering and Completeness Status

  • Numbering in this file is now strictly sequential.
  • All config classes from src/jazzmine/core/builder/configs.py are documented in this file.
  • Related aliases (StorageConfig, LLMConfig, DomainTerm) are also listed for completeness.

Builder: AgentBuilder

AgentBuilder is the fluent composition API for creating a fully wired Jazzmine agent.

Builder: errors

The errors module within the builder component is a specialized exception definition file. It defines ConfigError, which is the dedicated exception class used to signal misconfigurations during the agent construction phase. Though small in code size, it plays a vital role in the framework's "Fail-Fast" philosophy.

On this page

Full Coverage Index2.1 Config Classes2.2 Related Type Aliases (Not Classes)Storage Configuration Classes3.1 JsonStorage3.2 PostgresStorage3.3 MongoDBStorageLLM Configuration Classes4.1 OpenAILLMConfig4.2 AnthropicLLMConfig4.3 GeminiLLMConfig4.4 AzureLLMConfig4.5 CohereLLMConfig4.6 BedrockLLMConfig4.7 LocalLLMConfigEmbedding and Memory Configuration Classes5.1 EmbeddingConfig5.2 MemoryConfig5.2.1 Qdrant Connectivity5.2.2 Vector and Index Tuning5.2.3 Local Embedding Backend Fields5.2.4 Remote Embedding Backend FieldsSandbox and Runtime Configuration Classes6.1 FileMount6.2 SandboxSpec6.2.1 Identity and Runtime6.2.2 Resource Limits6.2.3 Pool and Storage6.2.4 Network and Mounts6.3 AgentSettingsSecurity and Server Configuration Classes7.1 SecurityConfig7.2 CORSConfig7.3 ServerConfig7.3.1 Network and Endpoints7.3.2 Auth, Limits, and Metadata7.3.3 CORS, TLS, and TuningValidation, Defaults, and Practical NotesNumbering and Completeness Status