Jazzmine

1. Behavior and Context

In the jazzmine architecture, ConfigError is tightly coupled with the AgentBuilder's validation lifecycle.

Synchronous Execution: This error is explicitly designed to be raised before any asynchronous I/O operations occur.
Pre-Flight Check: When a developer calls await builder.build(), the system runs a comprehensive, synchronous _validate() sweep over all provided configurations (LLMs, Memory, Sandboxes, Security, Server).
Aggregation: Instead of failing at the first typo, the builder collects all configuration violations into a list and raises a single ConfigError containing a bulleted summary of every mistake.

2. Purpose

Prevent Partial Initialization: Ensures that the system never reaches a state where a database connection is opened but a Docker container fails to spawn due to a bad config.
Developer Experience (DX): Saves developers time by presenting all configuration errors at once, rather than forcing them to fix one error, restart, and immediately hit another.
Strict Type/Value Enforcement: Acts as the boundary guard for configuration values (e.g., ensuring memory sizes are positive, ports are valid, and mutually exclusive settings are not mixed).

3. High-Level API (Usage)

Developers typically do not instantiate ConfigError directly, but they should be prepared to catch or read it during the initialization phase of their application.

Example: Catching a Configuration Error

python

import asyncio
from jazzmine.core.agent.builder import AgentBuilder
from jazzmine.core.builder.errors import ConfigError

async def main():
    # Intentionally bad configuration (missing required LLM)
    builder = AgentBuilder(
        name="Aria", 
        agent_id="aria_v1", 
        personality="Helpful bot"
    )
    
    try:
        # build() runs _validate() synchronously before any networking
        agent, teardown = await builder.build()
    except ConfigError as e:
        print("Failed to start the agent due to configuration issues:")
        print(e)
        
        # Output might look like:
        # Failed to start the agent due to configuration issues:
        # AgentBuilder validation failed:
        #   • No LLM configured. Call .llm(...) or .with_llm(instance).

if __name__ == "__main__":
    asyncio.run(main())

4. Detailed Functionality

Class: ConfigError(ValueError)

Inheritance: Inherits from Python's standard ValueError. This is semantically accurate, as the error represents inappropriate values passed into the builder's configuration methods.
Usage Context: Raised exclusively by AgentBuilder._validate(), AgentBuilder.settings(), and internal embedding setup checks when a configuration violates the framework's operational constraints.

5. Error Handling & Common Triggers

The ConfigError is typically triggered by the following common scenarios:

Missing Mandatory Components: Failing to provide an LLM configuration (.llm()).
Hardware/Constraint Violations: Providing negative values for Docker sandbox limits (e.g., memory_mb < 64 or pids_limit < 1).
Mutual Exclusivity: Attempting to configure both an input_moderator and a toxicity_detector in the SecurityConfig at the same time.
Port & Network Conflicts: Assigning invalid ports (< 1 or > 65535) to a sandbox's NetworkPolicy or the internal FastAPI ServerConfig.
Embedding Conflicts: Defining a remote embedding API key while simultaneously requesting local ONNX model generation.

6. Remarks

Clean Startup: By raising ConfigError synchronously, the framework guarantees that no orphaned Docker containers, stray temporary files, or dangling HTTP connections are left behind if the application fails to start.
Console Readability: The error string generated by the builder is explicitly formatted with newline characters and bullet points (•) to ensure it is highly readable in standard terminal outputs.

Builder: errors