koobi 0.0.2

File-native model and experiment registry

Koobi

File-native model and experiment registry for local workflows.

Koobi stores experiment metadata as plain Markdown cards, builds a disposable DuckDB index, and serves an interactive Marimo UI for browsing, filtering, visualizing, and editing cards. The source of truth is always your files.

Why Koobi

Most experiment trackers assume a hosted service and database-backed runs. Koobi is designed for local-first users who want:

• readable, versionable records in Git
• zero-server operation
• domain-agnostic metrics and parameters
• workflows friendly to both humans and coding agents

Current MVP Capabilities

• Markdown card parsing and serialization with preserved body/key ordering
• additive card updates (only targeted fields are rewritten)
• DuckDB index build with:
  • cards table (metadata + body)
  • measures table (long-format metrics)
  • series_registry table (series pointers)
• Marimo app with:
  • project/status/search filters
  • model table view
  • card detail view (metrics/params/tags/body)
  • edit form (name/status/tags/body) with write-back
  • one measure bar chart
• CLI commands:
  • koobi init
  • koobi new
  • koobi index
  • koobi ui

Architecture Overview

cards/*.md  -->  index.duckdb  -->  Marimo app
   ^                                  |
   |---------- edit/write-back -------|

• Cards are authoritative.
• Index is derived and disposable.
• UI reads from index and writes edits back to cards.

Installation

Install into any project or environment directly from Git:

pip install git+https://github.com/blu3c0ral/koobi.git

This installs the koobi command and the importable koobi package.

For local development on Koobi itself, install editable with dev extras:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

Quickstart

Koobi discovers its configuration automatically: every command searches the current directory and its parents for a koobi.toml. Work from inside your workspace and no --config flag is needed.

1) Create (or enter) a workspace

koobi init --path my-registry
cd my-registry

Or use the bundled demo workspace:

python examples/local_example_to_cards.py --overwrite
cd examples/local

2) Build the index

koobi index

3) Launch the UI

koobi ui

The UI opens at http://localhost:2718.

Running from outside the workspace

If you prefer not to cd, point Koobi at the config explicitly or via an environment variable (precedence: --config > KOOBI_CONFIG > current dir):

koobi ui --config examples/local/koobi.toml
# or
export KOOBI_CONFIG=examples/local/koobi.toml
koobi ui

CLI Reference

Initialize a new workspace:

koobi init --path /path/to/workspace

Create a new card (run from inside the workspace):

koobi new demo_project.my_model

Rebuild index:

koobi index

Run UI:

koobi ui

Use as a Library

Koobi's core is importable, so other projects and coding agents can read, query, and write cards programmatically:

from koobi import load_config, build, connect, query_cards
from koobi import Card, load_card, save_card

# Resolve config by searching upward from a path (file or directory)
cfg = load_config("path/to/workspace")

# Build the disposable DuckDB index from the Markdown cards
build(cfg)

# Query cards joined with wide-format measures
con = connect(cfg)
df = query_cards(con, project="demo_project", status="candidate")

# Read, mutate, and write back a single card (only targeted fields change)
card = load_card("path/to/workspace/cards/demo_project.my_model.md")
card.status = "promoted"
save_card(card, fields=["status"])

The full public API is exported from the top-level koobi package; see koobi.__all__.

Repository Layout

src/koobi/                  # core package (schema, cards, config, index, charts, app, cli)
tests/                      # unit tests
examples/local/             # self-contained demo workspace
examples/local_example_to_cards.py
docs/                       # product, technical, and future feature docs

Development

Run tests:

pytest

Recommended pre-PR checklist:

• run pytest
• regenerate local example cards if example inputs changed
• verify koobi index and koobi ui against examples/local/koobi.toml

Documentation

• docs/product_design.md - product framing and roadmap
• docs/technical_design.md - architecture and data contracts
• docs/future_features.md - planned automation and extensions

Status

Active MVP implementation with local example workflow included. Phase 0 focus is stability of file contracts, indexing, and interactive editing.