Concierge Core Kit

A FastAPI backend for conversational assistants, with durable conversations, tenant-aware resources and an MCP interface.

The source includes visitor turns and streaming, agent configuration, widget versions, connector policies, audit events and PostgreSQL migrations. It is a standalone extraction of Concierge Core, not the runtime for every agent in a company and not a replacement for a workflow engine or Tower.

Start with the offline suite

Requires Python 3.12–3.14. From a source checkout:

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python scripts/test_offline.py

The runner strips inherited credentials, ignores developer .env files and blocks real Python network connections. Tests use synthetic identities and mocked providers. The release was checked on Python 3.14: 2,174 passed; 10 database-dependent tests skipped. These numbers describe this exported suite, not a production deployment or an independent security audit.

Related MCP server: JouleOps MCP Server

Architecture

flowchart LR
  C["Console / visitor client"] --> H["HTTP + streaming"]
  A["Authorized MCP client"] --> M["MCP tools"]
  H --> P["Identity + tenant / action checks"]
  M --> P
  P --> D["PostgreSQL: agents, conversations, events, versions"]
  P --> K["Configured KB / connectors"]
  H --> R["Configured model provider"]

Local database verification

Use a dedicated disposable PostgreSQL 17 database. CONCIERGE_TEST_DSN is the only opt-in for tests that write to a real database; DATABASE_URL alone does not opt in.

export DATABASE_URL='postgresql://your_test_user@127.0.0.1:5432/concierge_test'
export KB_BASE_URL='https://kb.example.test'
export KB_TOKEN='synthetic-test-token'
export OPENROUTER_API_KEY='synthetic-test-key'
export ENV=test

# Emit the migration SQL, then apply it using psql.
# This path supports migrations containing multiple SQL statements.
.venv/bin/alembic upgrade head --sql > migration.sql
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f migration.sql
export CONCIERGE_TEST_DSN="$DATABASE_URL"
.venv/bin/pytest -q tests/test_bus.py tests/test_stream_routes.py \
  tests/test_widget_proof_nonce_db.py tests/test_erasure_matrix.py

Release verification ran those 11 checks on a fresh PostgreSQL 17 database with fsync, full_page_writes and synchronous_commit enabled. They cover concurrent event sequences, notifications, streams, proof nonce use and erasure. One check overlaps the offline suite. This is not a crash-survival or exhaustive concurrency claim.

Configure a running service

Copy .env.example to .env, fill the required settings and review every authentication setting for your environment. The example contains no usable credentials; the test values above cannot operate a real assistant. Migrate the chosen database separately, then:

.venv/bin/uvicorn app.main:create_app --factory --host 127.0.0.1 --port 8000

Provision tenants, agents, KB documents and caller permissions before serving conversations. /health is liveness; /ready also checks configured dependencies. The packaged persona and claims policies are synthetic examples, not company knowledge. The optional scripts/bootstrap_meta_concierge.py upserts an example tenant and agent in the configured database; inspect its model, caps and references before using it.

See the generated HTTP reference and MCP tool catalog. A listed tool is not a grant. Wiring a service token into a caller path does not establish caller authorization: review tenant, action and credential binding when integrating a KB or identity system.

Release scope

This source release excludes internal deployment configuration, customer knowledge, private differential-test references and company history. Synthetic examples replace customer fixtures and internal claims registries. MCP is constrained to the compatible 1.x SDK; Pydantic AI is pinned to the tested version. The console, KB server, Tower and production operations are separate projects.

No live model, voice, commerce, identity-provider or end-to-end client integration was exercised for this release. Do not expose an unconfigured checkout directly to the internet.

Apache-2.0. See LICENSE and NOTICE.