Configuration
obsei.yaml declares pipelines built only from registered plugins, so a config file can never
import arbitrary code. Secrets never go in the file: fields ending in _env name the environment
variable that holds the value.
obsei add writes sources, sinks and alerts into it for you, and with the schema line below your
editor completes and checks every key, including each plugin’s config
(Set up without editing YAML).
| Key | What it sets | Details |
|---|---|---|
store |
Database path and encryption | At rest and in use |
privacy |
Redaction regions, names, pseudonyms | Privacy controls |
egress |
Hosts feedback may be sent to | Privacy controls |
llms |
Classifier, embedding and chat models | Models |
themes |
Embedder, similarity, labels, k-anonymity | Themes |
access |
Tokens and roles for obsei serve |
Serve |
ask_llm, ask_judge, ask_judge_threshold |
Model and judge for obsei ask |
Ask |
plugins |
Installed plugins allowed to load | Plugins |
pipelines |
Sources, enrichers, routes and sinks | Sources, Routing, Sinks |
alerts |
Theme spikes, new themes, digests, health | Alerts |
# yaml-language-server: $schema=https://docs.obsei.com/schema/obsei.schema.jsonversion: 1
store: path: obsei.duckdb # OBSEI_DB overrides unencrypted: false # true only on an encrypted disk # air-gapped: pre-install httpfs, set OBSEI_DUCKDB_EXTENSIONS
privacy: redact: true regions: [global, north_america, uk, eu, latam, apac, india, africa]
egress: # optional; otherwise OBSEI_EGRESS_MODE / OBSEI_EGRESS_ALLOW mode: private allowed_hosts: [my-tenant.openai.azure.com]
llms: default: api: local # in-process classifier (obsei[local]) ollama: base_url: http://localhost:11434/v1 model: qwen3:8b azure: base_url: https://my-tenant.openai.azure.com/openai/v1 model: gpt-5-mini api_key_env: AZURE_OPENAI_API_KEY max_requests: 2000
plugins: [reddit] # installed plugins allowed to load (reddit: see Sources)
pipelines: - name: reviews batch_size: 100 sources: - key: ios type: appstore config: {app_id: "284882215", countries: [us, de, br, jp, in, ng]} enrichers: - type: classify config: {llm: default, fallback_llm: azure, threshold: 0.7} sinks: - type: slack config: {when: {classify.intent: [bug, churn_risk]}}Sinks take an optional key (default: their type), and a pipeline can add ordered route: rules
that send each record to the sinks of the first rule it matches; see Routing.
Alerts
Section titled “Alerts”Top-level alerts: watch aggregates rather than records: theme spikes, new themes, digests, the
review queue and pipeline health. Each names the sinks that deliver it in to, written like
pipeline sinks; see Alerts.
alerts: - name: spikes kind: theme_spike # new_theme, digest, review_queue or pipeline_health to: - type: slack config: {webhook_url_env: SLACK_ALERTS_URL}Enrichers
Section titled “Enrichers”Enrichers run in the order listed, on new or changed records only.
| Type | What | Model |
|---|---|---|
filter |
One yes/no question per record; matching records are tagged or dropped | decision |
classify |
Sentiment, intent, language and your own fields, with a confidence | local, decision or chat |
classify takes llm, fallback_llm, threshold, min_confidence, sentiments, intents and
fields; see Models for local and decision endpoints, option descriptions and
cutoffs. Put filter first so dropped records never reach the classifier:
enrichers: - type: filter config: llm: julia # an llms entry with api: decision question: Is this spam rather than a real customer request? yes_means: prize scams, phishing links, advertising or bulk mail # optional, with no_means no_means: a customer writing about a product, an account or a bill threshold: 0.8 # probability of yes from which a record matches (default 0.5) action: drop # or tag (default): keep it with filter.match: true - type: classify config: {llm: julia, fallback_llm: ollama}Dropped records are not classified, delivered or stored; the run summary counts them
(dropped 3). A source that returns the same record again (a feed without a cursor) has it checked
again. With action: tag, sinks can skip matches with when: {filter.match: ["false"]}.
obsei ask, POST /api/ask and the Slack command answer from your feedback with ask_llm. Add
ask_judge, a decision endpoint, to check each answer against the records it cites: the judge gets
only the question, the answer and the cited records (redacted, as stored) and answers “Is every
statement in the answer supported by the quoted records?”.
ask_llm: ollamaask_judge: kev # an llms entry with api: decisionask_judge_threshold: 0.5 # defaultThe CLI prints grounded: 0.93, and below the threshold warns that the answer may not be
supported. The API returns grounded and possibly_unsupported, and Slack replies carry a
warning line. Judging needs a capable model: in our tests Julia-1 did not separate supported from
unsupported answers, so use a 4B or larger decision model (Kev-4B, lev, Clef-Flash) as the judge.
How a run works
Section titled “How a run works”- Each source resumes from its saved cursor and yields records.
- Records are redacted, then compared with the stored copy; unchanged records stop here.
- Enrichers label new or changed records; a
filterwithaction: dropremoves records here. - Records go to sinks: with a
route:, each sink a route names gets only the records routed to it, and every other sink gets the batch through its ownwhen. Only then is the batch stored and the cursor advanced, so a failed run retries the same batch (at-least-once; sinks are idempotent by record id).
A failing pipeline is reported and the others still run; obsei run then exits with status 1.
Scheduling
Section titled “Scheduling”Set every_minutes on a pipeline and obsei serve runs it on that schedule, sharing the server’s
database. DuckDB allows a single writer, so do not point a separate obsei run at a database that
obsei serve holds. themes.auto: true updates themes after each scheduled run, alerts are
checked after that, and GET /api/runs reports the last run of each pipeline.
themes: auto: truepipelines: - name: reviews every_minutes: 60 sources: [...]Without a server, obsei run --every 60 repeats the run every hour.