eve Company Brain

The eve Company Brain is an agent template that lets teams ask questions about dbt models and their underlying data from Slack, answering via constrained SQL executed against either a local DuckDB file or MotherDuck tables.

What is the eve Company Brain?

The eve Company Brain is an agent template built on eve, the open framework for building agents. It takes dbt model documentation and a DuckDB or MotherDuck database as input, then produces threaded conversational answers in Slack or an authenticated terminal UI. The example project uses the Apache 2.0-licensed dbt Jaffle Shop dataset (100 customers, 99 orders dated January 1–April 9, 2018).

What makes the eve Company Brain stand out?

• Three authored tools — list_models, get_model, and query_sql are the only actions the agent can take; the same client, SQL, and tools work for local DuckDB and MotherDuck.
• dbt-generated catalog — pnpm data:build runs dbt plus all tests, then compiles manifest.json and catalog.json into agent/lib/catalog.ts, including descriptions, column types, compiled SQL, dependencies, and authored meta values for grain, joins, metrics, and caveats.
• SQL parsing, not regex filtering — the query tool parses statements with DuckDB's serializer, accepting one SELECT with non-recursive CTEs and joins while rejecting writes, multiple statements, metadata commands, table functions, and recursive queries.
• Hard result limits — at most 200 rows, 32 columns, 64 KiB of column and row data, 16 KiB of SQL, four concurrent queries per process, and a 15-second local interrupt.
• Slack admission policy — SLACK_ALLOWED_USER_IDS, SLACK_ALLOWED_CHANNEL_IDS, and SLACK_TEAM_ID are all required, using exact IDs rather than names or wildcards.
• HTTP Basic operator access — a generated COMPANY_BRAIN_HTTP_PASSWORD enables the terminal UI; an empty value disables HTTP entirely, and production HTTP access stays off.
• Read-only local database — the DuckDB file uses two threads, a 256 MiB memory limit, and no disk spill, with external access disabled.
• Catalog scoping — only models tagged company_brain, materialized as tables in main with snake_case names, are exposed.

Who should use the eve Company Brain?

• Analytics engineers who already maintain dbt projects and want a Slack-facing question-answering layer over existing model documentation.
• Data platform teams evaluating how constrained SQL plus a generated catalog can limit what an LLM agent can query.
• Agent developers who want a working reference for eve's Slack channel, HTTP Basic operator sessions, and local-bash workspace.

What can you do with the eve Company Brain?

• Answer metric questions in Slack: ask “What is included in our payment totals?” and receive a threaded answer grounded in the model catalog; the sample's recorded order payments total AUD 1,672 across all statuses and payment methods.
• Explore sample data locally: the seeded Jaffle Shop data covers 100 customers and 99 orders, so you can test queries like monthly payment totals before pointing at real tables.
• Switch backends without rewriting tools: change DUCKDB_CONNECTION from a file path to md:jaffle_shop to target MotherDuck (which additionally needs a Read Scaling token and its own copy of the models).

How does the eve Company Brain work?

The pipeline is CSV seeds → dbt build and tests → DuckDB file or MotherDuck tables, plus dbt docs generate → agent/lib/catalog.ts. At query time, a Slack message or operator session reaches the eve agent, which reads model definitions, writes constrained SQL, runs it against the selected database, and posts a threaded answer. Regenerate the catalog and rebuild the agent after changing models, and stop the local agent before rebuilding the DuckDB file so dbt can open a writer connection.

Pros and cons

• The template is explicitly not a production access-control or metrics platform: there is no separate semantic layer, vector database, or persistent business memory.
• Everybody admitted through a Slack conversation uses the same warehouse identity, and the template does not check Slack Connect membership or move sensitive results to DMs.
• MotherDuck read replicas are eventually consistent and may lag writes by a few minutes, and the template cannot verify a token's permissions.
• Local resource limits are not a budget for MotherDuck's remote compute; result limits do not cap the number of source rows scanned.

FAQ

Does the eve Company Brain require Docker or a warehouse account?

No. For the local database, you need Node.js 24 or newer, pnpm 12, and uv (which runs the data command through Python 3.13). No Docker daemon or warehouse account is needed; model calls require an AI Gateway credential or Vercel project OIDC.

Can I point the eve Company Brain at MotherDuck?

Yes. Create a MotherDuck database named jaffle_shop, build the example there with a writer token, then set DUCKDB_CONNECTION=md:jaffle_shop and provide a Read Scaling token in the deployed environment. Changing the connection does not upload your local database.

Why can't I use the local self-modification editor with HTTP Basic auth?

The bundled editor accepts only localDev() or linked-project Vercel development identities, not the template's http-basic principal. Edit files in agent/ directly; eve dev reloads changes. The template advises against adding localDev() as a fallback, since it could admit tunnel-forwarded callers.

What happens if I ask about “last month”?

The sample data spans January 1–April 9, 2018, and the catalog timestamp records metadata generation, not source-data freshness. The agent is instructed to clarify ambiguous metric definitions and report the sample's historical window rather than silently substituting it for “last month.”

Can I use my own dbt models?

Yes. Replace the dbt project, tag only the tables intended for the agent, and enrich descriptions and meta definitions. Models must be tables in main with snake_case names, and you should review model SQL and catalog content before publishing.