agent-platform

agent-platform

基于 Python 的多服务智能体开发平台脚手架。

当前仓库已经初始化为 Monorepo，包含：

• services/：核心微服务
• libs/：共享领域模型、DSL、事件、数据库和公共组件
• deployments/：本地和集群部署占位
• docs/：规划和数据库设计文档

当前已创建的服务

• api-gateway
• model-gateway-service
• session-service
• agent-service
• memory-service
• team-service
• skill-service
• human-service
• knowledge-service
• event-service
• auth-service
• scheduler-service
• tool-service

每个服务都提供了最小 FastAPI 启动入口和健康检查接口，数据库相关服务也已经带上了 SQLAlchemy 模型骨架与 Alembic 目录。

当前已创建的共享库

• core-domain
• core-dsl
• core-events
• core-shared
• core-db

推荐本地开发方式

建议使用 uv 或 pip 创建虚拟环境后安装各服务依赖。

cd D:\workspace\auto-platform
python -m venv .venv
.venv\Scripts\activate
pip install -e .\libs\core-shared
pip install -e .\libs\core-domain
pip install -e .\libs\core-dsl
pip install -e .\libs\core-events
pip install -e .\libs\core-db
pip install -e .\services\api-gateway
pip install -e .\services\session-service
pip install -e .\services\agent-service
pip install -e .\services\memory-service
pip install -e .\services\team-service
pip install -e .\services\skill-service
pip install -e .\services\human-service
pip install -e .\services\knowledge-service
pip install -e .\services\event-service
pip install -e .\services\auth-service
pip install -e .\services\scheduler-service
pip install -e .\services\tool-service

运行示例：

cd D:\workspace\auto-platform\services\api-gateway
uvicorn app.main:app --reload --port 8000

数据库连接默认使用 PostgreSQL，可以通过环境变量覆盖：

$env:AGENT_PLATFORM_DATABASE_URL="postgresql+psycopg://user:password@localhost:5432/agent_db"

数据层脚手架

本轮已经加入：

• libs/core-db：统一 SQLAlchemy Base、通用 mixin、命名约定
• session-service：会话与消息模型
• tool-service：工具定义与绑定模型
• 每个服务独立的 alembic.ini、env.py、versions/
• session-service：已接入 repository / application service / CRUD API

迁移执行示例：

cd D:\workspace\auto-platform\services\session-service
alembic upgrade head

其他服务同理：

• services/tool-service

接口示例：

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8001/sessions `
  -ContentType "application/json" `
  -Body '{"app_id":"app-1","user_id":"user-1","channel_type":"web"}'

工具定义示例：

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8004/tools `
  -ContentType "application/json" `
  -Body '{"code":"search_products","name":"Search Products","tool_type":"http"}'

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8004/tools/versions `
  -ContentType "application/json" `
  -Body '{"tool_id":"tool-1","input_schema_json":{"query":{"type":"string"}},"invoke_config_json":{"method":"GET","path":"/products/search"}}'

目录结构

services/
  api-gateway/
  session-service/
  skill-service/
  human-service/
  knowledge-service/
  event-service/
  auth-service/
  scheduler-service/
  tool-service/
libs/
  core-domain/
  core-dsl/
  core-events/
  core-shared/
  core-db/
deployments/
  docker/
  k8s/
docs/
tests/

下一步建议

1. 补齐 V0.1 的 repository / service 层
2. 写第一版 Alembic 初始迁移
3. 接入 PostgreSQL / Redis
4. 增加 Docker Compose
5. 开始实现会话、代理、团队主链路

Agent Service APIs

agent-service stores strongly typed agent definitions, versioned prompts/configuration, and agent run records.

Create an agent:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8007/agents `
  -ContentType "application/json" `
  -Body '{"code":"sales_agent","name":"Sales Agent","agent_type":"assistant"}'

Create a published agent version:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8007/agents/versions `
  -ContentType "application/json" `
  -Body '{"agent_id":"agent-id","status":"published","role":"sales_assistant","goal":"Help qualify leads","system_prompt":"You are a careful sales assistant."}'

Enable multi-step ReAct planning for an agent version:

{
  "model_config": {
    "react_enabled": true,
    "react_max_steps": 5
  }
}

When ReAct is enabled, the model can emit JSON tool actions such as {"action":"tool","tool_code":"lookup_order","input_json":{"order_id":"123"}} and then finish with {"action":"finish","answer":"..."}. Each tool call is persisted in agent_tool_invocation.

Create an agent run. If agent_version_id is omitted, the latest published version is used:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8007/agents/runs `
  -ContentType "application/json" `
  -Body '{"agent_id":"agent-id","session_id":"session-id","input_text":"Summarize this lead."}'

List tool invocation records for an agent run:

Invoke-RestMethod `
  -Uri "http://127.0.0.1:8007/agents/runs/agent-run-id/tool-invocations"

Agent execution now persists tool invocation audit records with selected, running, skipped, completed, or failed status, including input/output payloads and started_time / finished_time.

Through api-gateway, use /gateway/agents/**.

Memory Service APIs

memory-service stores scoped memories for users, sessions, agents, and teams. The first version uses database text search so it works without vector infrastructure; pgvector can be added later behind the same API.

Memory search now stores a local deterministic embedding per memory and uses hybrid rerank:

• keyword_score: token overlap and frequency
• vector_score: cosine similarity over local hash embeddings
• importance_score: normalized memory importance boost
• rerank_mode: hybrid-local

Create a memory:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8008/memories `
  -ContentType "application/json" `
  -Body '{"scope_type":"session","scope_id":"session-id","memory_type":"fact","content_text":"User prefers concise answers.","importance_score":80}'

Search memories:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8008/memories/search `
  -ContentType "application/json" `
  -Body '{"query":"concise","scope_type":"session","scope_id":"session-id","limit":5}'

Through api-gateway, use /gateway/memories/**.

Team Service APIs

team-service stores multi-agent team definitions, versioned member composition, coordination mode, and team run records. The first version provides the team management backbone; later versions can connect team runs to supervisor/planner/member agent execution.

Create a team:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8009/teams `
  -ContentType "application/json" `
  -Body '{"code":"research_team","name":"Research Team","team_type":"collaborative"}'

Create a published team version:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8009/teams/versions `
  -ContentType "application/json" `
  -Body '{"team_id":"team-id","status":"published","coordination_mode":"supervisor","objective":"Research and summarize complex questions","member_refs":[{"member_key":"lead","agent_id":"agent-lead","role":"supervisor","responsibility":"Plan and assign work"},{"member_key":"writer","agent_id":"agent-writer","role":"executor","responsibility":"Draft final answer"}]}'

Create a team run. If team_version_id is omitted, the latest published version is used:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8009/teams/runs `
  -ContentType "application/json" `
  -Body '{"team_id":"team-id","session_id":"session-id","input_text":"Analyze this customer request."}'

Through api-gateway, use /gateway/teams/**.

Execute a team run. The first implementation creates and executes one agent run per member, then stores a team-level summary. dry_run=true lets this work without model API keys:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8009/teams/runs/team-run-id/execute `
  -ContentType "application/json" `
  -Body '{"worker_key":"team-worker-1","dry_run":true}'

Execute one queued team run through the worker claim API:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8009/teams/workers/execute-next `
  -ContentType "application/json" `
  -Body '{"worker_key":"team-worker-1","lease_seconds":300,"dry_run":true}'

Run a standalone team worker process:

Push-Location .\services\team-service
$env:AGENT_PLATFORM_DATABASE_URL="postgresql+psycopg://admin:password@git.newpoint.work:5432/vectordb"
$env:AGENT_PLATFORM_WORKER_DRY_RUN="true"
..\..\.venv\Scripts\python -m app.worker
Pop-Location

Skill Service APIs

skill-service stores reusable skill definitions, versioned parameter/output schemas, marketplace-style installations, and executable skill runs. The first executor supports a dependency-free template runtime so local development works without API keys.

Create a skill:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8010/skills `
  -ContentType "application/json" `
  -Body '{"code":"hello_user","name":"Hello User","skill_type":"template"}'

Create a published skill version:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8010/skills/versions `
  -ContentType "application/json" `
  -Body '{"skill_id":"skill-id","status":"published","runtime_type":"template","parameter_schema_json":{"name":{"type":"string"}},"implementation_json":{"template":"Hello $name"}}'

Install the skill for an agent, team, app, or user scope:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8010/skills/installations `
  -ContentType "application/json" `
  -Body '{"skill_id":"skill-id","install_scope":"workspace","scope_id":"t1","installed_by":"user-1"}'

Create and execute a skill run:

$run = Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8010/skills/runs `
  -ContentType "application/json" `
  -Body '{"skill_id":"skill-id","input_json":{"name":"Lucas"}}'

Invoke-RestMethod -Method Post `
  -Uri "http://127.0.0.1:8010/skills/runs/$($run.id)/execute" `
  -ContentType "application/json" `
  -Body '{"worker_key":"skill-worker-1"}'

Through api-gateway, use /gateway/skills/**.

Human Service APIs

human-service stores human-in-the-loop tasks for approval, input collection, takeover, pause, and resume flows.

Create an approval task:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8011/human/tasks `
  -ContentType "application/json" `
  -Body '{"task_type":"approval","title":"Approve refund","run_id":"run-id","node_run_id":"node-run-id","assigned_to":"ops-1","request_payload_json":{"amount":99}}'

Claim and complete a task:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8011/human/tasks/human-task-id/claim `
  -ContentType "application/json" `
  -Body '{"claimed_by":"ops-1"}'

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8011/human/tasks/human-task-id/complete `
  -ContentType "application/json" `
  -Body '{"status":"approved","response_payload_json":{"approved":true}}'

Through api-gateway, use /gateway/human/**.

Knowledge Service APIs

knowledge-service stores independent knowledge bases, documents, chunks, and retrieval results. It defaults to deterministic local hash embeddings plus keyword scoring, so it works without external API keys. For production, set AGENT_PLATFORM_EMBEDDING_PROVIDER=http with an OpenAI-compatible /embeddings endpoint; if the provider fails and fallback is enabled, indexing and search fall back to local hash embeddings.

When running on PostgreSQL with pgvector, knowledge_chunk.embedding_vector is populated and search uses pgvector cosine similarity first, then combines it with keyword scoring. PostgreSQL with pgvector is the supported retrieval database for this platform.

Create a knowledge base:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8012/knowledge/bases `
  -ContentType "application/json" `
  -Body '{"code":"support_kb","name":"Support Knowledge Base"}'

Create and index a document:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8012/knowledge/documents `
  -ContentType "application/json" `
  -Body '{"knowledge_base_id":"kb-id","title":"Refund Policy","content_text":"Refunds are available within seven days for eligible orders.","source_type":"text"}'

Search the knowledge base:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8012/knowledge/search `
  -ContentType "application/json" `
  -Body '{"knowledge_base_id":"kb-id","query":"refund within seven days","top_k":3}'

Through api-gateway, use /gateway/knowledge/**.

Event Service APIs

event-service stores platform events with delivery status so services can use a durable outbox pattern now, and later swap delivery to Kafka/RabbitMQ behind the same API.

Publish an event:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8013/events `
  -ContentType "application/json" `
  -Body '{"event_type":"run.created","source_service":"agent-service","aggregate_type":"agent_run","aggregate_id":"run-id","payload_json":{"run_id":"run-id"}}'

Claim pending events for a delivery worker:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8013/events/claim-pending `
  -ContentType "application/json" `
  -Body '{"limit":50}'

Through api-gateway, use /gateway/events/**.

Auth Service APIs

auth-service stores users, roles, role assignments, and permission checks. This is the RBAC layer for platform governance.

$user = Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8014/auth/users `
  -ContentType "application/json" `
  -Body '{"username":"alice","display_name":"Alice"}'

$role = Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8014/auth/roles `
  -ContentType "application/json" `
  -Body '{"code":"admin","name":"Admin","permissions_json":["*"]}'

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8014/auth/assignments `
  -ContentType "application/json" `
  -Body "{`"user_id`":`"$($user.id)`",`"role_id`":`"$($role.id)`"}"

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8014/auth/permissions/check `
  -ContentType "application/json" `
  -Body "{`"user_id`":`"$($user.id)`",`"permission`":`"agent:write`"}"

Through api-gateway, use /gateway/auth/**.

Scheduler Service APIs

scheduler-service stores delayed jobs and due-job leases for time-based automation. It is intentionally service-neutral: jobs can target HTTP, event, agent, or team execution.

Create a scheduled job:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8015/scheduler/jobs `
  -ContentType "application/json" `
  -Body '{"job_type":"agent","name":"Run agent later","schedule_time":"2026-04-26T12:00:00Z","payload_json":{"agent_run_id":"run-id"}}'

Claim due jobs for a worker:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8015/scheduler/jobs/claim-due `
  -ContentType "application/json" `
  -Body '{"worker_key":"scheduler-worker-1","limit":20}'

Mark a job completed or failed:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8015/scheduler/jobs/job-id/status `
  -ContentType "application/json" `
  -Body '{"status":"completed"}'

Through api-gateway, use /gateway/scheduler/**.

Run the scheduler worker locally:

Push-Location .\services\scheduler-service
$env:AGENT_PLATFORM_DATABASE_URL="postgresql+psycopg://admin:password@git.newpoint.work:5432/vectordb"
$env:AGENT_PLATFORM_EVENT_SERVICE_URL="http://127.0.0.1:8013"
python -m app.worker
Pop-Location

Execute an agent run without calling an external model:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8007/agents/runs/agent-run-id/execute `
  -ContentType "application/json" `
  -Body '{"worker_key":"agent-worker-1","dry_run":true}'

Execute with model-gateway-service:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8007/agents/runs/agent-run-id/execute `
  -ContentType "application/json" `
  -Body '{"worker_key":"agent-worker-1"}'

Agent memory policy is stored on agent_version.memory_policy_json:

• enabled: read memories before execution
• memory_scope: one of user, session, agent, or team
• read_top_k: maximum memories to inject into the prompt
• write_enabled: write a conversation memory after successful model execution
• config_json.write_importance_score: optional importance score for written memories

Agent capability refs are stored on agent_version.tool_refs_json and agent_version.skill_refs_json.

• Tool refs are selected when required=true, config_json.auto_invoke=true, or selection_keywords match the run input.
• Skill refs are selected by default unless config_json.auto_invoke=false; selection_keywords can also select them.
• Dry-run execution returns selected_tool_refs and selected_skill_refs without calling downstream tools/skills.
• Normal execution invokes selected HTTP tool bindings and selected skills before the model call, then injects their results into the model messages.

Example version with session memory:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8007/agents/versions `
  -ContentType "application/json" `
  -Body '{"agent_id":"agent-id","status":"published","role":"assistant","system_prompt":"Use relevant memory when helpful.","memory_policy":{"enabled":true,"memory_scope":"session","read_top_k":5,"write_enabled":true,"config_json":{"write_importance_score":60}}}'

Execute one queued agent run through the worker claim API:

Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8007/agents/workers/execute-next `
  -ContentType "application/json" `
  -Body '{"worker_key":"agent-worker-1","lease_seconds":300,"dry_run":true}'

Run a standalone agent worker process:

Push-Location .\services\agent-service
$env:AGENT_PLATFORM_DATABASE_URL="postgresql+psycopg://admin:password@git.newpoint.work:5432/vectordb"
$env:AGENT_PLATFORM_WORKER_DRY_RUN="true"
..\..\.venv\Scripts\python -m app.worker
Pop-Location

API Gateway

api-gateway provides a unified entrypoint:

• GET /gateway/services/health
• /gateway/sessions/** -> session-service /sessions/**
• /gateway/agents/** -> agent-service /agents/**
• /gateway/memories/** -> memory-service /memories/**
• /gateway/teams/** -> team-service /teams/**
• /gateway/skills/** -> skill-service /skills/**
• /gateway/human/** -> human-service /human/**
• /gateway/knowledge/** -> knowledge-service /knowledge/**
• /gateway/events/** -> event-service /events/**
• /gateway/auth/** -> auth-service /auth/**
• /gateway/scheduler/** -> scheduler-service /scheduler/**
• /gateway/tools/** -> tool-service /tools/**
• /gateway/models/** -> model-gateway-service /models/**
• /gateway/code/** -> code-runner-service /code/**

Gateway readiness:

Invoke-RestMethod -Uri "http://127.0.0.1:8000/ready"

Downstream health:

Invoke-RestMethod -Uri "http://127.0.0.1:8000/gateway/services/health"

Gateway request context:

• Incoming x-request-id is reused; otherwise gateway generates one.
• Incoming x-workspace-id is reused; otherwise gateway falls back to workspace_id query parameter, then public.
• Gateway forwards both x-request-id and x-workspace-id to downstream services.
• Gateway writes request audit records to gateway_request_audit.

Query gateway audits:

Invoke-RestMethod `
  -Uri "http://127.0.0.1:8000/gateway/audits?limit=20" `
  -Headers @{}

Query gateway audit stats:

Invoke-RestMethod `
  -Uri "http://127.0.0.1:8000/gateway/audits/stats" `
  -Headers @{}

Gateway API Key auth:

• AGENT_PLATFORM_AUTH_REQUIRED=false by default for local development.
• Set AGENT_PLATFORM_AUTH_REQUIRED=true to protect /gateway/**, except /gateway/services/health.
• API keys are stored as SHA-256 hashes. The raw key is only returned once at creation.
• When auth is enabled and no API key exists yet, the first POST /gateway/api-keys is allowed as bootstrap.
• API keys can be active, disabled, or revoked; only active keys are accepted.
• If an API key has scopes, gateway checks them before proxying. Use *, gateway:agents:*, or exact permissions such as gateway:agents:read.
• Set AGENT_PLATFORM_AUTHZ_REQUIRED=true to require x-user-id and call auth-service /auth/permissions/check for the derived permission.

Create an API key:

$body = @{
    name = "local-dev"
  scopes = "gateway:agents:*"
} | ConvertTo-Json

$created = Invoke-RestMethod `
  -Method Post `
  -Uri "http://127.0.0.1:8000/gateway/api-keys" `
  -ContentType "application/json" `
  -Body $body

$created.api_key

Use an API key:

Invoke-RestMethod `
  -Uri "http://127.0.0.1:8000/gateway/audits" `
  -Headers @{"x-api-key"=$created.api_key}

Disable or revoke an API key:

$body = @{
    status = "revoked"
} | ConvertTo-Json

Invoke-RestMethod `
  -Method Patch `
  -Uri "http://127.0.0.1:8000/gateway/api-keys/$($created.id)/status" `
  -ContentType "application/json" `
  -Headers @{"x-api-key"=$created.api_key} `
  -Body $body

Recommended environment variables for model-gateway-service:

$env:AGENT_PLATFORM_PROVIDER_BASE_URL="https://api.openai.com/v1"
$env:AGENT_PLATFORM_PROVIDER_API_KEY="your-api-key"
$env:AGENT_PLATFORM_DEFAULT_MODEL="gpt-4o-mini"

Recommended environment variables for code-runner-service:

$env:AGENT_PLATFORM_PYTHON_BIN="python"
$env:AGENT_PLATFORM_MAX_TIMEOUT_SECONDS="30"

Docker Compose

Files:

• deployments/docker/docker-compose.yml
• deployments/docker/python-service.Dockerfile
• deployments/docker/.env.example

Start all services locally:

cd D:\workspace\auto-platform
Copy-Item .\deployments\docker\.env.example .\.env
docker compose -f .\deployments\docker\docker-compose.yml up --build

Start in detached mode:

docker compose -f .\deployments\docker\docker-compose.yml up --build -d

Production-like infrastructure:

• Compose now starts postgres with the pgvector image and runs CREATE EXTENSION IF NOT EXISTS vector.
• Compose now starts durable redis with append-only persistence.
• Copy deployments/docker/.env.example to .env to use per-service PostgreSQL databases such as agent_service and knowledge_service.
• Set AGENT_PLATFORM_REDIS_URL=redis://redis:6379/0 to enable shared Redis-backed locks, idempotency keys, and queues.

Run all service migrations:

python .\scripts\migrate_all.py

Run only selected migrations:

python .\scripts\migrate_all.py --only agent-service --only knowledge-service

Run the automated smoke tests:

pip install pytest
pytest -q

The repository includes .gitlab-ci.yml with a Python 3.11 test job that installs the core libraries plus Agent/Knowledge services, runs compileall, and executes the pytest smoke suite.

Scale agent workers:

docker compose -f .\deployments\docker\docker-compose.yml up --build -d --scale agent-worker=3

Scale team workers:

docker compose -f .\deployments\docker\docker-compose.yml up --build -d --scale team-worker=3

Scale scheduler workers:

docker compose -f .\deployments\docker\docker-compose.yml up --build -d --scale scheduler-worker=3

Stop and remove containers:

docker compose -f .\deployments\docker\docker-compose.yml down

Important notes:

• Services default to PostgreSQL; set AGENT_PLATFORM_DATABASE_URL explicitly for each environment.
• Scaled workers should use PostgreSQL plus Redis for locks, queues, idempotency, and leases.
• core-shared.redis_primitives provides DistributedLock, IdempotencyStore, and RedisQueue for services that need cross-process coordination.
• agent-worker and scheduler-worker use Redis locks/idempotency when Redis is available, and fall back to DB leases when Redis is not available.
• agent-service stores agent definitions, prompt/config versions, and agent run records under /data
• memory-service stores scoped memories under /data; move it to PostgreSQL before enabling high-volume memory writes
• team-service stores multi-agent team definitions, team versions, and team run records under /data
• team-worker executes queued team runs by orchestrating member agent runs; it can be scaled independently
• skill-service stores skill definitions, versions, marketplace-style installations, and skill execution runs under /data
• human-service stores human approval, input, pause/resume, and takeover task records under /data
• knowledge-service stores knowledge bases, documents, chunks, and local retrieval metadata under /data
• event-service stores platform events and delivery status under /data
• auth-service stores users, roles, assignments, and permission policy metadata under /data
• scheduler-service stores delayed jobs, due-job leases, and retry status under /data
• agent-worker has no exposed port and can be scaled independently; set AGENT_PLATFORM_AGENT_WORKER_DRY_RUN=true for no-key local smoke runs
• scheduler-worker has no exposed port and can be scaled independently; prefer PostgreSQL for real multi-worker write concurrency
• model-gateway-service defaults to http://host.docker.internal:11434/v1; replace it in .env if you want OpenAI or another OpenAI-compatible provider