Metadata-Version: 2.4
Name: koobi
Version: 0.0.2
Summary: File-native model and experiment registry
Author-email: blu3c0ral <blu3c0ral@protonmail.ch>
License-Expression: MIT
Project-URL: Homepage, https://github.com/blu3c0ral/koobi
Project-URL: Repository, https://github.com/blu3c0ral/koobi
Project-URL: Issues, https://github.com/blu3c0ral/koobi/issues
Keywords: experiment-tracking,model-registry,marimo,duckdb,markdown
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: altair>=5
Requires-Dist: duckdb>=0.10
Requires-Dist: marimo>=0.23
Requires-Dist: pandas>=2
Requires-Dist: pyarrow>=14
Requires-Dist: pyyaml>=6
Requires-Dist: tomli; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# Koobi

<p align="center">
  <img src=".github/assets/koobi_icon.png" alt="Koobi project icon" width="180" />
</p>

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

```text
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:

```bash
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:

```bash
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

```bash
koobi init --path my-registry
cd my-registry
```

Or use the bundled demo workspace:

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

### 2) Build the index

```bash
koobi index
```

### 3) Launch the UI

```bash
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):

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

## CLI Reference

Initialize a new workspace:

```bash
koobi init --path /path/to/workspace
```

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

```bash
koobi new demo_project.my_model
```

Rebuild index:

```bash
koobi index
```

Run UI:

```bash
koobi ui
```

## Use as a Library

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

```python
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

```text
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:

```bash
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`](docs/product_design.md) - product framing and roadmap
- [`docs/technical_design.md`](docs/technical_design.md) - architecture and data contracts
- [`docs/future_features.md`](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.
