Jazzmine

1. Introduction

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.

2. Full Coverage Index

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

2.1 Config Classes

Class	Category	Used by
JsonStorage	Storage	AgentBuilder.storage(...)
PostgresStorage	Storage	AgentBuilder.storage(...)
MongoDBStorage	Storage	AgentBuilder.storage(...)
OpenAILLMConfig	LLM	AgentBuilder.llm(...), AgentBuilder.script_gen_llm(...)
AnthropicLLMConfig	LLM	AgentBuilder.llm(...), AgentBuilder.script_gen_llm(...)
GeminiLLMConfig	LLM	AgentBuilder.llm(...), AgentBuilder.script_gen_llm(...)
AzureLLMConfig	LLM	AgentBuilder.llm(...), AgentBuilder.script_gen_llm(...)
CohereLLMConfig	LLM	AgentBuilder.llm(...), AgentBuilder.script_gen_llm(...)
BedrockLLMConfig	LLM	AgentBuilder.llm(...), AgentBuilder.script_gen_llm(...)
LocalLLMConfig	LLM	AgentBuilder.llm(...), AgentBuilder.script_gen_llm(...)
EmbeddingConfig	Embedding export	AgentBuilder.embeddings(...)
MemoryConfig	Memory/Qdrant	AgentBuilder.memory(...)
FileMount	Sandbox mount helper	SandboxSpec.file_mounts
SandboxSpec	Sandbox runtime	AgentBuilder.sandbox(...)
AgentSettings	Runtime tuning	AgentBuilder.settings(...)
SecurityConfig	Security guard	AgentBuilder.security(...)
CORSConfig	HTTP server CORS	ServerConfig.cors
ServerConfig	HTTP server	AgentBuilder.server(...)

2.2 Related Type Aliases (Not Classes)

Alias	Definition
StorageConfig	JsonStorage \| PostgresStorage \| MongoDBStorage
LLMConfig	OpenAILLMConfig \| AnthropicLLMConfig \| GeminiLLMConfig \| AzureLLMConfig \| CohereLLMConfig \| BedrockLLMConfig \| LocalLLMConfig
DomainTerm	tuple[str, str, str, list[str], str]

3. Storage Configuration Classes

3.1 JsonStorage

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

Parameter	Type	Default	Description
path	str	""	JSON path. Empty string means auto temp file created by builder.

3.2 PostgresStorage

PostgreSQL message/trace storage.

Parameter	Type	Default	Description
dsn	str	Required	PostgreSQL DSN (example: postgresql://user:pass@host:5432/dbname).
pool_min	int	2	Minimum asyncpg pool size.
pool_max	int	10	Maximum asyncpg pool size.

3.3 MongoDBStorage

MongoDB message/trace storage.

Parameter	Type	Default	Description
uri	str	Required	MongoDB URI (example: mongodb://user:pass@host:27017).
db	str	"jazzmine"	Database name.

4. 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.).

Parameter	Type	Default	Description
model	str	Required	Model identifier.
api_key	str	Required	API key (Bearer token style).
base_url	str	Required	Base URL of provider API.
temperature	float	0.5	Sampling temperature.
max_tokens	int	1024	Max output tokens.
timeout	float	90.0	Request timeout in seconds.
top_p	float \| None	None	Nucleus sampling parameter.
chat_endpoint	str	"/v1/chat/completions"	Chat endpoint path.

4.2 AnthropicLLMConfig

Anthropic Claude provider.

Parameter	Type	Default	Description
model	str	Required	Claude model ID.
api_key	str	Required	Anthropic API key.
base_url	str	"https://api.anthropic.com"	API base URL.
temperature	float	0.5	Sampling temperature.
max_tokens	int	1024	Max output tokens.
timeout	float	90.0	Request timeout in seconds.

4.3 GeminiLLMConfig

Google Gemini provider via Generative Language API.

Parameter	Type	Default	Description
model	str	Required	Gemini model ID.
api_key	str	Required	Google API key.
base_url	str	"https://generativelanguage.googleapis.com"	API base URL.
temperature	float	0.5	Sampling temperature.
max_tokens	int	1024	Max output tokens.
timeout	float	90.0	Request timeout in seconds.

4.4 AzureLLMConfig

Azure OpenAI deployment config.

Parameter	Type	Default	Description
api_key	str	Required	Azure key.
endpoint	str	Required	Azure resource endpoint URL.
deployment_name	str	Required	Azure deployment name.
api_version	str	"2024-02-15-preview"	API version string.
temperature	float	0.5	Sampling temperature.
max_tokens	int	1024	Max output tokens.
timeout	float	90.0	Request timeout in seconds.

4.5 CohereLLMConfig

Cohere Command provider config.

Parameter	Type	Default	Description
api_key	str	Required	Cohere API key.
model	str	"command-r-plus"	Cohere model ID.
temperature	float	0.5	Sampling temperature.
max_tokens	int	1024	Max output tokens.
timeout	float	90.0	Request timeout in seconds.

4.6 BedrockLLMConfig

AWS Bedrock model config.

Parameter	Type	Default	Description
model	str	Required	Bedrock model ID.
region_name	str	Required	AWS region name.
temperature	float	0.5	Sampling temperature.
max_tokens	int	1024	Max output tokens.
timeout	float	90.0	Kept for API consistency.

4.7 LocalLLMConfig

Local subprocess model config.

Parameter	Type	Default	Description
binary_path	str	Required	Executable path. Must support -p "<prompt>" mode.
model	str	"local"	Telemetry label.
temperature	float	0.5	Sampling temperature.
max_tokens	int	1024	Max output tokens.
timeout	float	90.0	Informational in local mode.

5. Embedding and Memory Configuration Classes

5.1 EmbeddingConfig

Automatic local embedding export and tokenizer setup.

Parameter	Type	Default	Description
model_id	str	"BAAI/bge-small-en-v1.5"	Hugging Face model ID.
output_dir	str	""	Output directory (empty means default under ~/.jazzmine/models).
tokenizer_only	bool	False	Only export tokenizer, skip ONNX model export.
quantized	bool	True	Export quantized ONNX model.
opset	int	17	ONNX opset.
force_rebuild	bool	False	Force re-download/re-export.

5.2 MemoryConfig

Qdrant and embedding backend runtime configuration.

5.2.1 Qdrant Connectivity

Parameter	Type	Default	Description
qdrant_url	str	Required	Qdrant URL.
tokenizer_path	str	""	Tokenizer path (auto-resolved when embeddings() is used).
collection_prefix	str	"jazzmine"	Collection prefix.
qdrant_api_key	str \| None	None	Qdrant API key.
qdrant_auto_start	bool	True	Auto-start local Qdrant container when relevant.
qdrant_docker_image	str	"qdrant/qdrant"	Docker image for auto-start mode.
qdrant_container_name	str \| None	None	Optional container name override.
qdrant_http_host_port	int \| None	None	HTTP host port override.
qdrant_data_volume	str	"jazzmine-qdrant-data"	Docker volume for Qdrant data.
qdrant_stop_on_shutdown	bool	True	Stop auto-started Qdrant on teardown.

5.2.2 Vector and Index Tuning

Parameter	Type	Default	Description
vector_size	int	384	Embedding vector size.
distance_metric	str	"cosine"	Similarity metric.
use_indexing	bool	True	Enable ANN indexing.
quantization	int \| None	8	Vector quantization bits (None, 4, or 8).
on_disk	bool	False	Store vectors on disk.
replication_factor	int	1	Replica count.
shard_number	int	1	Shard count.
indexing_threshold	int	2000	Segment indexing threshold.
flush_interval_sec	int	15	Flush interval.
max_optimization_threads	int	1	Optimization thread count.
use_sparse_vectors	bool	True	Enable sparse vectors for hybrid retrieval.

5.2.3 Local Embedding Backend Fields

Parameter	Type	Default	Description
model_dir	str \| None	None	Local ONNX model directory.
quantized	bool	False	Whether local model is quantized.
max_batch	int	8	Local embedding batch size.

5.2.4 Remote Embedding Backend Fields

Parameter	Type	Default	Description
embed_provider	str	"openai"	Remote embed provider identifier.
embed_api_key	str \| None	None	Remote API key.
embed_base_url	str \| None	None	Remote base URL override.
embed_model_name	str \| None	None	Remote model name override.

6. Sandbox and Runtime Configuration Classes

6.1 FileMount

Host path mapping helper used by SandboxSpec.file_mounts.

Parameter	Type	Default	Description
host_path	str	Required	Host filesystem path.
container_path	str	Required	Path mounted inside sandbox container.
read_only	bool	True	Read-only mount toggle.
docker_host_path	str \| None	None	Docker host path override for DooD scenarios.

6.2 SandboxSpec

Sandbox execution environment specification.

6.2.1 Identity and Runtime

Parameter	Type	Default	Description
name	str	Required	Sandbox identifier.
python_version	str	"3.11"	Base Python version for sandbox image.
execution_mode	str	"plan"	Default mode: plan or interactive.

6.2.2 Resource Limits

Parameter	Type	Default	Description
cpu_quota	float	0.5	CPU quota.
memory_mb	int	256	Memory cap in MB.
memory_swap_mb	int	-1	Swap cap (-1 for unlimited).
pids_limit	int	64	Max process/thread count.
timeout_sec	int	30	Execution timeout.
max_output_bytes	int	1048576	Output cap.

6.2.3 Pool and Storage

Parameter	Type	Default	Description
scratch_size_mb	int	128	Scratch filesystem size in MB.
pool_size	int	1	Warm container count.
pool_max_overflow	int	10	Overflow container allowance.
pool_host_path_map	dict[str, str]	{}	Prefix map for host-path translation in DooD setups.

6.2.4 Network and Mounts

Parameter	Type	Default	Description
allowed_hosts	list[str]	[]	Egress host allowlist.
allowed_ports	dict[str, list[int]]	{}	Per-host allowed ports.
default_port	int	443	Default port when no per-host override exists.
file_mounts	list[FileMount]	[]	Bind mounts.
pip_packages	list[str]	[]	Packages baked into sandbox image.
secrets	dict[str, str]	{}	Runtime environment secrets.

6.3 AgentSettings

High-level behavior tuning for the runtime pipeline.

Parameter	Type	Default	Description
default_sandbox_name	str	""	Default sandbox fallback.
default_execution_mode	str	"plan"	Default execution mode fallback.
max_task_calls_per_turn	int	4	Max tool task calls per turn.
max_interactive_steps	int	4	Max interactive steps.
max_retries	int	3	Script generation retry count.
episodic_same_conv_limit	int	3	Same-conversation episodic recall limit.
episodic_prev_conv_limit	int	1	Previous-conversation episodic recall limit.
semantic_top_k	int	4	Semantic term recall limit.
enhancer_history_window	int	8	Message enhancer history window.
summarizer_trigger	int	3	Unsummarized threshold before summarizer runs.
max_episode_size	int	20	Max episode size.
min_episode_size	int	2	Min episode size.
episode_overlap	int	1	Episode overlap count.
flow_top_k	int	3	Flow candidate recall limit.
flow_rrf_k	int	10	RRF k for flow ranking.
pool_max_overflow	int	10	Global pool overflow cap.
pool_host_path_map	dict[str, str]	{}	Global host path map for pool path translation.

7. Security and Server Configuration Classes

7.1 SecurityConfig

Security guard injection and policy thresholds.

Parameter	Type	Default	Description
input_moderator	Any \| None	None	Input moderator instance.
toxicity_detector	Any \| None	None	Toxicity detector instance.
output_moderator	Any \| None	None	Output moderator instance.
file_sanitizer	Any \| None	None	File sanitizer instance.
input_confidence_threshold	float	0.5	Input block threshold.
output_confidence_threshold	float	0.5	Output block threshold.
input_block_message	str	long default	Message shown on input block.
output_block_message	str	long default	Message shown on output block.
moderation_timeout	float	10.0	Timeout per moderation call.
fail_open	bool	True	Timeout/exception behavior.

7.2 CORSConfig

CORS policy model used inside ServerConfig.

Parameter	Type	Default	Description
origins	list[str]	["*"]	Allowed origins.
allow_credentials	bool	False	Allow credentials in CORS.
allow_methods	list[str]	["*"]	Allowed HTTP methods.
allow_headers	list[str]	["*"]	Allowed request headers.
expose_headers	list[str]	[]	Exposed response headers.
max_age	int	600	Preflight cache seconds.

7.3 ServerConfig

HTTP server behavior for builder-managed API server.

7.3.1 Network and Endpoints

Parameter	Type	Default	Description
host	str	"0.0.0.0"	Bind host.
port	int	1453	Bind port.
chat_endpoint	str	"/chat"	Chat endpoint path.
conversations_endpoint	str	"/conversations"	Conversations endpoint base path.
health_endpoint	str	"/health"	Health endpoint path.
info_endpoint	str	"/info"	Info endpoint path.

7.3.2 Auth, Limits, and Metadata

Parameter	Type	Default	Description
api_key	str \| None	None	Bearer auth key when enabled.
request_timeout	float	120.0	Request timeout seconds.
max_message_length	int	32768	Maximum message length.
title	str	"Jazzmine Agent API"	API title.
description	str	""	API description.
api_version	str	"1.0.0"	API version string.
docs_url	str \| None	"/docs"	Swagger URL (None disables).
redoc_url	str \| None	None	ReDoc URL.

7.3.3 CORS, TLS, and Tuning

Parameter	Type	Default	Description
cors	CORSConfig	CORSConfig()	CORS policy object.
ssl_certfile	str \| None	None	SSL certificate file path.
ssl_keyfile	str \| None	None	SSL private key file path.
log_level	str	"info"	Uvicorn log level.
backlog	int	2048	Socket backlog size.
limit_concurrency	int \| None	None	Max concurrent requests.
timeout_keep_alive	int	5	Keep-alive timeout seconds.

8. 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.

9. 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: Configuration Models