Configuration Module

This module provides LLM configuration and tool functions.

LLM Router

agentsociety2.config.get_llm_router(model_type='default')

Get (and cache) the LLM Router for a specific purpose.

Parameters:

model_type (str) – default / coder / nano / analysis。

Returns:

LiteLLM litellm.router.Router instance (in-process singleton cache).

Return type:

Router

agentsociety2.config.get_llm_router_and_model(model_type='default')

Get the Router and model names at the same time (Router uses cache).

Parameters:

model_type (str) – default / coder / nano / analysis。

Returns:

(router, model_name)。

Return type:

tuple[Router, str]

Config class

class agentsociety2.config.Config

AgentSociety2 configuration (environment variable source).

This class exposes configuration items in the form of “class attributes” for easy reading without instantiation.

Main environment variables (excerpt):

• AGENTSOCIETY_HOME_DIR: Data directory

• AGENTSOCIETY_LLM_API_KEY / AGENTSOCIETY_LLM_API_BASE / AGENTSOCIETY_LLM_MODEL: Default model configuration

• AGENTSOCIETY_CODER_LLM_*: Code generation model configuration

• AGENTSOCIETY_EMBEDDING_*：embedding configuration

HOME_DIR: str = './agentsociety_data'

Base directory path for storing agent data, memories, and persistent files.

Environment variable: AGENTSOCIETY_HOME_DIR Default: “./agentsociety_data”

This directory will contain subdirectories for memories, agent states, and other persistent data. The path can be absolute or relative to the current working directory.

LLM_API_KEY: str | None = 'docs-build-placeholder'

API key for authenticating with the default LLM service.

Environment variable: AGENTSOCIETY_LLM_API_KEY Default: None (must be set for the system to function)

This is the primary API key used for most LLM operations. If not set, the system will raise an error when attempting to create LLM routers. Other specialized LLM configurations (coder, nano, embedding) will fall back to this key if their specific keys are not provided.

LLM_API_BASE: str = 'https://api.openai.com/v1'

Base URL endpoint for the default LLM API service.

Environment variable: AGENTSOCIETY_LLM_API_BASE Default: “https://api.openai.com/v1”

This should point to the API endpoint expected by the selected LiteLLM provider. For OpenAI-compatible gateways, include the protocol (https://) and base path, but not the specific model endpoint (e.g., /chat/completions).

LLM_MODEL: str = 'gpt-5.5'

Model identifier for the default LLM used in general operations.

Environment variable: AGENTSOCIETY_LLM_MODEL Default: “gpt-5.5”

This model is used for most language understanding and generation tasks that don’t require specialized models. The model name should match the LiteLLM provider/model id used by your API provider; “gpt-5.5” is only the default OpenAI example.

CODER_LLM_API_KEY: str | None = 'docs-build-placeholder'

API key for the code generation LLM service.

Environment variable: AGENTSOCIETY_CODER_LLM_API_KEY Default: Falls back to LLM_API_KEY if not set

This key is used specifically for code-related operations. If not provided, the system will use the default LLM_API_KEY. Setting a separate key allows you to use a different API provider or account for code generation tasks, which may have different rate limits or pricing structures.

CODER_LLM_API_BASE: str = 'https://api.openai.com/v1'

Base URL endpoint for the code generation LLM API.

Environment variable: AGENTSOCIETY_CODER_LLM_API_BASE Default: Falls back to LLM_API_BASE if not set

Allows you to use a different API endpoint specifically for code generation tasks. This is useful if you want to route code generation requests to a different service or region for better performance or cost optimization.

CODER_LLM_MODEL: str = 'gpt-5.5'

Model identifier for code generation and programming tasks.

Environment variable: AGENTSOCIETY_CODER_LLM_MODEL Default: Falls back to LLM_MODEL if not set

This model is specifically used for code generation, code analysis, and other programming-related operations. Choose a model that is optimized for code understanding and generation, such as models trained on codebases.

EMBEDDING_API_KEY: str | None = 'docs-build-placeholder'

API key for the embedding model service.

Environment variable: AGENTSOCIETY_EMBEDDING_API_KEY Default: Falls back to LLM_API_KEY if not set

This key is used specifically for embedding operations, which convert text into high-dimensional vectors for semantic search, similarity matching, and memory operations. Some providers offer separate embedding services with different pricing.

EMBEDDING_API_BASE: str = 'https://api.openai.com/v1'

Base URL endpoint for the embedding API service.

Environment variable: AGENTSOCIETY_EMBEDDING_API_BASE Default: Falls back to LLM_API_BASE if not set

Allows you to use a different API endpoint specifically for embedding operations. Some providers have dedicated embedding endpoints that may offer better performance or different pricing models for embedding tasks.

EMBEDDING_MODEL: str = 'text-embedding-3-large'

Model identifier for text embedding generation.

Environment variable: AGENTSOCIETY_EMBEDDING_MODEL Default: “text-embedding-3-large”

This model is used to convert text into dense vector representations (embeddings). The embeddings are used for semantic search, similarity matching, and storing memories in vector databases. Choose a model that produces high-quality embeddings for your use case and language.

EMBEDDING_DIMS: int = 1024

Dimensionality of the embedding vectors produced by the embedding model.

Environment variable: AGENTSOCIETY_EMBEDDING_DIMS Default: 1024

This specifies the size of the vector space for embeddings. Higher dimensions can capture more nuanced semantic information but require more storage and computation. The value must match the actual output dimensionality of the selected embedding model. Common values are 384, 512, 768, 1024, or 1536 depending on the model.

TRACE_WRITER_ASYNC: bool = True

ENV_ACTOR_MAX_CONCURRENCY: int = 8

LLM_LATENCY_DEGRADE_FACTOR: float = 4.0

Relative latency backoff factor for AIMD. A non-error LLM call is counted as “slow” (and contributes to an AIMD decrease) when its latency exceeds baseline * factor, where baseline is a rolling low-percentile (P25) of recent healthy latencies.

Environment variable: AGENTSOCIETY_LLM_MODEL Default: “gpt-5.5”

The baseline tracks the fast path, so this triggers when calls are genuinely slow relative to recent good performance — robust to the initial concurrent burst. Set to a very large value (or inf) to disable relative latency backoff and rely on rate-limit (429) errors alone (the previous behavior).

LLM_SLOW_LATENCY_MS: float | None = None

Optional absolute SLO ceiling in milliseconds. A non-error LLM call slower than this counts as “slow” regardless of the rolling baseline. Catches pathological tails even when sustained contention has pushed the whole baseline up (where the relative factor goes blind).

Environment variable: AGENTSOCIETY_LLM_MODEL Default: “gpt-5.5”

LLM_ROUND_SAMPLE_CAP: int = 64

Upper bound on AIMD round size (completions evaluated per adjustment). Without this cap, round size grows with the limit, so a large limit makes adaptation sluggish (e.g. limit 400 → 400 completions before any adjust).

Environment variable: AGENTSOCIETY_LLM_MODEL Default: “gpt-5.5”

LLM_RAY_MAX_WORKERS: int = 2

Upper bound used as the Ray CPU budget hint (ray.init(num_cpus=...)).

Environment variable: AGENTSOCIETY_LLM_RAY_MAX_WORKERS Default: machine logical CPU count (os.cpu_count()).

Caps how many step_agent_batch Ray Tasks run concurrently per tick (one task per BATCH_SIZE chunk of agents). Lower this below the physical core count to leave headroom for the driver, the env-router actor, and the trace/replay actors.

v = None

LLM_RAY_CONCURRENCY: int = 16

Initial per-process concurrency for local LLM dispatching.

Environment variable: AGENTSOCIETY_LLM_RAY_CONCURRENCY Default: 16

The starting concurrency each local LLMClient AIMD semaphore tunes from. There is no hard upper/lower cap — each process adjusts its concurrency freely via AIMD (additive increase / multiplicative decrease) based on observed latency and rate-limit errors.

BATCH_SIZE: int = 256

Number of agents per step_agent_batch Ray Task.

Environment variable: AGENTSOCIETY_BATCH_SIZE Default: 256

Each simulation tick chunks the agent id list into batches of this size and submits one Ray Task per chunk (tasks = ceil(N / BATCH_SIZE)). At most LLM_RAY_MAX_WORKERS tasks run concurrently, so choose a size where ceil(N / BATCH_SIZE) >= LLM_RAY_MAX_WORKERS to saturate the workers; otherwise some workers sit idle. Smaller batches add scheduling overhead; larger batches mean one slow agent can stall its whole batch.

LITERATURE_SEARCH_MCP_URL: str = 'https://llmapi.fiblab.net/mcp/'

Base URL for the literature search service.

Environment variable: LITERATURE_SEARCH_API_URL Default: “http://localhost:8008/api/search”

LITERATURE_SEARCH_API_KEY: str = ''

API key for the literature search service authentication.

Environment variable: LITERATURE_SEARCH_API_KEY Default: “” (empty, must be set for authenticated requests)

classmethod get_router(model_type='default')

Get the LLM Router for the specified purpose (without global caching).

Parameters:

model_type (Literal['default', 'coder']) – default / coder / nano / analysis。

Returns:

LiteLLM litellm.router.Router Instance.

Raises:

ValueError – Thrown when the required API key is not configured.

Return type:

Router

classmethod get_literature_search_mcp_url()

Return the normalized academic literature MCP gateway URL.

Returns:

URL from LITERATURE_SEARCH_MCP_URL (environment overrides class default).

Return type:

str

classmethod get_literature_search_api_key()

Return the Bearer token for the literature MCP gateway.

Returns:

Key from LITERATURE_SEARCH_API_KEY (environment overrides class default).

Return type:

str

classmethod get_default_router()

Returns:

LLM Router for default use.

Return type:

Router

Utility function

agentsociety2.config.extract_json(text)

Extract JSON string fragments from text as robustly as possible.

This function only “intercepts” and is not responsible for repairing illegal JSON; if it needs to be repaired, please cooperate with tools such as json_repair.

Parameters:

text (str) – May contain JSON text (such as LLM output, possibly mixed with Markdown code fences).

Returns:

The extracted JSON text; returns None if not found.

Return type:

str | None