Configuration¶

All services are configured through environment variables. Copy the example file and fill in values:

cp ai-engine-api/.env.example ai-engine-api/.env

AI Engine API¶

Vector store (Qdrant)¶

Variable	Purpose	Example
`QDRANT_API_URL`	Qdrant endpoint	`http://localhost:6333`
`QDRANT_API_KEY`	Qdrant API key (cloud)	`your-key`
`COLLECTION_NAME`	collection name	`omeka-items`
`FIELD_NAME_GEO`	geo payload field	`locations`
`EMBEDDING_MODEL`	embedding model id	`sentence-transformers/all-MiniLM-L6-v2`
`SEARCH_LIMIT`	default result count	`5`

Online serving (Redis)¶

Variable	Purpose	Example
`REDIS_URL`	Redis endpoint for the recsys event buffer and the materialized user model	`redis://localhost:6379/0`

If REDIS_URL or QDRANT_API_URL are unset, the recsys layer uses in-memory fakes.

LLM (narratives)¶

Variable	Purpose	Example
`OPENROUTER_API_URL`	OpenRouter endpoint	`https://openrouter.ai/api/v1`
`OPENROUTER_API_KEY`	OpenRouter key	`your-key`
`OPENROUTER_NARRATIVE_MODEL`	model id	`arliai/qwq-32b-arliai-rpr-v1:free`
`OLLAMA_BASE_URL`	Ollama endpoint	`http://localhost:11434`
`OLLAMA_MODEL`	Ollama model	`llama3.3:latest`

Auth (Keycloak, for the MEMORISE LLM gateway)¶

Only needed if your LLM endpoint sits behind the MEMORISE Keycloak gateway.

Variable	Purpose
`KEYCLOAK_BASE_URL`	Keycloak server
`KEYCLOAK_REALM`	realm (`oauth2-proxy`)
`KEYCLOAK_CLIENT_ID`	client id
`KEYCLOAK_CLIENT_SECRET`	client secret
`KEYCLOAK_USERNAME` / `KEYCLOAK_PASSWORD`	service account credentials
`KEYCLOAK_SAFETY_MARGIN_SECONDS`	refresh margin before token expiry (`30`)

Application tuning¶

Variable	Purpose	Default
`READING_SPEED_WPS`	words per second for reading-time estimates	`4.2`
`IMG_EXTRA_FIXED_TIME`	extra seconds for an image	`1.3`

Content Engine¶

The content-engine service writes to the same Qdrant collection the API reads.

Variable	Purpose	Default
`QDRANT_API_URL`	Qdrant endpoint (required)	none
`QDRANT_API_KEY`	Qdrant API key	none
`COLLECTION_NAME`	target collection	`omeka-items`
`EMBEDDING_MODEL`	embedding model id	`sentence-transformers/all-MiniLM-L6-v2`
`INGEST_API_KEY`	shared secret for write endpoints; if unset, writes are public	none

Set INGEST_API_KEY in production

With INGEST_API_KEY unset the POST /ingest and POST /sync/omeka endpoints are open. Set it and send the value in the X-API-Key header.

Consistency rule¶

COLLECTION_NAME and EMBEDDING_MODEL must match between the Content Engine (writer) and the AI Engine API (reader). If they differ, the recommender reads an empty or mismatched collection.