配置模块

本模块提供 LLM 配置与工具函数。

LLM Router

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

获取（并缓存）指定用途的 LLM Router。

参数:

model_type (str) -- default / coder。

返回:

LiteLLM litellm.router.Router 实例（进程内单例缓存）。

返回类型:

Router

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

同时获取 Router 与模型名（Router 使用缓存）。

参数:

model_type (str) -- default / coder。

返回:

(router, model_name)。

返回类型:

tuple[Router, str]

Config 类

class agentsociety2.config.Config

AgentSociety2 配置（环境变量来源）。

该类以“类属性”的形式暴露配置项，便于在不实例化的情况下读取。

主要环境变量（节选）：

• AGENTSOCIETY_HOME_DIR：数据目录

• AGENTSOCIETY_LLM_API_KEY / AGENTSOCIETY_LLM_API_BASE / AGENTSOCIETY_LLM_MODEL：默认模型配置

• AGENTSOCIETY_CODER_LLM_*：代码生成模型配置

• AGENTSOCIETY_EMBEDDING_*：embedding 配置

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, 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_LATENCY_DEGRADE_FACTOR Default: 4.0

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_SLOW_LATENCY_MS Default: unset (relative-factor backoff only)

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_ROUND_SAMPLE_CAP Default: 64

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/'

MCP gateway URL for academic literature search (Streamable HTTP).

Environment variable: LITERATURE_SEARCH_MCP_URL Default: "https://llmapi.fiblab.net/mcp/"

LITERATURE_SEARCH_API_KEY: str = ''

Bearer token for literature MCP authentication.

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

classmethod get_router(model_type='default')

获取指定用途的 LLM Router（不做全局缓存）。

参数:

model_type (Literal['default', 'coder']) -- default / coder。

返回:

LiteLLM litellm.router.Router 实例。

抛出:

ValueError -- 当所需 API key 未配置时抛出。

返回类型:

Router

classmethod get_literature_search_mcp_url()

Return the normalized academic literature MCP gateway URL.

返回:

URL from LITERATURE_SEARCH_MCP_URL (environment overrides class default).

返回类型:

str

classmethod get_literature_search_api_key()

Return the Bearer token for the literature MCP gateway.

返回:

Key from LITERATURE_SEARCH_API_KEY (environment overrides class default).

返回类型:

str

classmethod get_default_router()

返回:

默认用途的 LLM Router。

返回类型:

Router

工具函数

agentsociety2.config.extract_json(text)

从文本中尽量稳健地提取 JSON 字符串片段。

该函数只做“截取”，不负责修复不合法 JSON；若需要修复，请配合 json_repair 等工具。

参数:

text (str) -- 可能包含 JSON 的文本（例如 LLM 输出，可能夹杂 Markdown code fences）。

返回:

提取出的 JSON 文本；若未找到则返回 None。

返回类型:

str | None