Skip to content

Quickstart

1. Install

pip install oa-configurator

2. Configure your first package

After installing a package that supports oa_configurator, run its configure command:

omop-config configure <package>   # e.g. omop_alchemy, omop_emb

The command asks for the settings that this package needs, helps you create or reuse related items such as databases and models, and then writes ~/.config/omop/config.toml. Run it again whenever you need to change that package's settings.

Before saving, configure checks the complete setup, including items named by package defaults. An interactive run offers to create or select missing connections, databases, providers, models, and vector stores. In a script, create the named item first or use the package's nested --set options to create it as part of the same command. A failed check leaves your existing configuration unchanged.

To create an empty config file without prompts (useful for scripted setups), use:

omop-config init

Safety

Passwords and API Keys are currently stored in plaintext. Keep the file readable only by your user: chmod 600 ~/.config/omop/config.toml. Secret management improvements are planned for a future release.

3. Configure an LLM/embedding model (optional)

Packages that call an LLM or embedding model (e.g. omop-emb, omop-spires) reference one by name via their own package-specific setting. For fields the package marks for this, omop-config configure <package> resolves them for you: it offers to reuse an existing [models.*] entry, or create one on the spot, recursing into [providers.*] the same way if the provider doesn't exist yet either.

To manage [providers.*]/[models.*] entries directly, outside of any specific package's configure flow, use the standalone commands:

omop-config providers add <provider-name>   # e.g. local-ollama
omop-config models add <model-name>         # e.g. nomic-embed

providers add prompts for the omop-llm provider key (ollama, llamacpp, vllm, openai, anthropic, gemini), base URL, and API key. models add prompts for which provider it's served through, the model name, embedding_dim/document_prefix/query_prefix, and then for each of the four capability fields — embeddings, tool_use, structured_output, extended_thinking — as a yes/no confirm. Capabilities are opt-in and default to false: neither any-llm nor omop-llm can introspect them per model, so anything you don't declare is treated as unsupported. An embedding model therefore needs embeddings = true, and setting embedding_dim without it is rejected outright.

Both commands accept flags for non-interactive use, with the capability fields as paired boolean flags:

omop-config models add nomic-embed \
    --provider local-ollama --model nomic-embed-text:v1.5 \
    --embeddings --embedding-dim 768 \
    --document-prefix "search_document: " --query-prefix "search_query: "

Passing any flag switches the command out of interactive mode: unflagged fields then fall back to their stored value (when updating an existing entry) or their default (when creating a new one) instead of prompting, and a required field with neither is an error. Run with --help for the full list.

List what's configured:

omop-config providers list
omop-config models list

See Config reference for the full field list, and omop-llm's Asymmetric Embeddings guide for what document_prefix/query_prefix are for.

4. Verify

omop-config show

Prints your config as JSON. Validation errors (unknown field, missing cross-reference) appear here.

5. Test connectivity

omop-config verify

Reports OK / FAIL for each configured connection, with latency.

6. Export for Docker Compose

omop-config export-env

Writes ~/.config/omop/config.env. Docker Compose services read it via env_file:.

Verbosity

All omop-config commands accept -v / -vv to increase log output:

omop-config -v verify     # INFO level
omop-config -vv show      # DEBUG level

Next steps