# 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:

```sh
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.

## Architecture

```mermaid
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"]
```

| Included | Requires your deployment |
| --- | --- |
| FastAPI application and MCP tool implementations | TLS, service configuration and tenant provisioning |
| PostgreSQL schema and migrations through `0032` | PostgreSQL and backup operations |
| Visitor token, origin and principal checks | Identity provider, keys and correctly scoped grants |
| KB and model client integrations | Compatible KB service and provider credentials |
| Voice, widget and connector integration code | Their external services and client applications |

## 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.

```sh
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:

```sh
.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](docs-public/api/endpoints.md) and [MCP tool catalog](docs-public/mcp/tools-catalog.md). 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](LICENSE) and [NOTICE](NOTICE).