tycoon

A pip-installable CLI for local-first data analytics. No Docker, no cloud account required. Works with your existing stack or builds one from scratch.

Default pipeline: dlt → DuckDB → dbt → Rill (dashboards) + Nao (AI queries)

Adaptable: bring your own ingestion (Airbyte, Fivetran), warehouse (Snowflake, BigQuery, MotherDuck), dbt project, BI tool, or orchestrator — tycoon init asks before it assumes.

---

Install

pip install tycoon
# or
uv add tycoon

For Dagster orchestration:

pip install "tycoon[dagster]"

For AI natural language queries:

pip install "tycoon[ask]"

For the web UI (coming in 0.2):

pip install "tycoon[server]"

Requirements: Python >= 3.12

---

Quickstart

# 1. Initialize a project — wizard asks about your existing stack
mkdir my-project && cd my-project
tycoon init

# 2. Add a data source
tycoon data sources add rest_api

# 3. Ingest data
tycoon data sources run my-rest-api

# 4. Transform with dbt
tycoon data transform run

# 5. Start dashboards, Dagster, and the AI agent
tycoon start

Already have a pipeline? tycoon init will ask about your ingestion tool, warehouse, dbt project, BI tool, and orchestrator — and configure itself around what you already have.

---

CLI Reference

Command	Description
tycoon init	Scaffold a new project
tycoon data sources catalog	Browse available source integrations
tycoon data sources add <type>	Register a new data source
tycoon data sources list	List sources configured in this project
tycoon data sources list show <name>	Show detailed config for a source
tycoon data sources run <name>	Run ingestion for a named source
tycoon data sources run-all	Run ingestion for all sources
tycoon data transform run	Run dbt transformations
tycoon data analyze <source>	Scaffold dbt models and Rill dashboards for a source
tycoon data db query <sql>	Run a SQL query against the warehouse
tycoon data run-all	Ingest all sources then run dbt build
tycoon data status	Show freshness and row counts for each source
tycoon start	Start Rill, Dagster, Nao, and the web UI
tycoon stop	Stop all services
tycoon ask chat	Query your data in natural language (Nao)
tycoon run <tool>	Passthrough to dbt, dlt, rill, dagster

---

tycoon.yml Reference

name: my-project
version: 0.1.0

database:
  raw: data/raw.duckdb              # dlt output (or md: URI for MotherDuck)
  warehouse: data/warehouse.duckdb  # dbt output — read by Rill and Nao

dbt_project_dir: dbt_project   # path to dbt project (yours or tycoon-scaffolded)
rill_dir: rill                 # path to Rill dashboard definitions

stack:                         # generated by tycoon init — edit as needed
  ingestion: dlt               # dlt | airbyte | fivetran | meltano | none
  ingestion_managed: true      # false = tycoon won't run `data sources run`
  warehouse: duckdb            # duckdb | motherduck | snowflake | bigquery | other
  transformation_managed: true # false = tycoon won't scaffold or overwrite dbt
  bi: rill                     # rill | metabase | looker | tableau | other | none
  bi_managed: true             # false = tycoon won't start Rill
  orchestrator: dagster        # dagster | airflow | prefect | other | none
  orchestrator_managed: true   # false = tycoon won't start Dagster

sources:
  my-github:
    type: github               # matches a catalog source name
    schema: raw_github         # schema name in the raw DuckDB file
    config:
      access_token: ${GITHUB_TOKEN}   # env vars are interpolated
      owner: my-org
      repo: my-repo

ask:                           # optional — requires tycoon[ask]
  llm:
    provider: ollama           # fully local, no API key required
  port: 5005

Each source produces its own raw DuckDB file: data/raw_<source>.duckdb. All sources write into data/warehouse.duckdb after transformation.

---

Catalog Sources

These sources are available via tycoon data sources add <name>. They are downloaded on demand via dlt init and not bundled in the package.

Source	Category	Key Tables
github	Developer	commits, issues, pull_requests, repositories
slack	Communication	channels, messages, users
stripe	Finance	customers, invoices, products, subscriptions
hubspot	CRM	companies, contacts, deals, tickets
notion	Knowledge	databases, pages, users

---

Data Directory

Raw DuckDB files follow the naming convention raw_<source>.duckdb (written by ingestion) while warehouse.duckdb is the single transformed database read by Rill and Nao. See data/README.md for details.

---

Rill Dashboards

Rill is a local-first BI tool that reads directly from DuckDB. Dashboard definitions are YAML files in the rill/ directory. Launch Rill via tycoon start or tycoon start --only rill.

---

Optional Extras

Dagster orchestration (tycoon[dagster])

Installs Dagster, dagster-dbt, and dagster-dlt. Provides a full asset graph covering ingestion and transformation. Run the Dagster UI with:

dagster dev

The workspace is defined in workspace.yaml at the project root.

AI queries (tycoon[ask])

Installs Nao and Ibis for natural language querying of the warehouse. Requires a running LLM — Ollama (local) is supported out of the box with no API key.

tycoon ask init
tycoon ask sync
tycoon ask chat