koobi 0.0.1__py3-none-any.whl

koobi/__init__.py

@@ -0,0 +1,35 @@
+"""Koobi: file-native model and experiment registry.
+
+This module exposes the stable public API. Import the high-level helpers
+directly from ``koobi`` rather than reaching into submodules::
+
+    from koobi import load_config, build, connect, query_cards
+    from koobi import Card, load_card, save_card
+"""
+
+from __future__ import annotations
+
+from .cards import iter_cards, load_card, save_card
+from .charts import measure_bar
+from .config import Config, load_config
+from .index import build, connect, query_cards
+from .schema import Card, SeriesRef, dump_card, parse_card
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "__version__",
+    "Card",
+    "Config",
+    "SeriesRef",
+    "build",
+    "connect",
+    "dump_card",
+    "iter_cards",
+    "load_card",
+    "load_config",
+    "measure_bar",
+    "parse_card",
+    "query_cards",
+    "save_card",
+]

koobi/app.py

@@ -0,0 +1,214 @@
+"""Marimo app entrypoint for Koobi."""
+
+import marimo
+
+__generated_with = "0.23.10"
+app = marimo.App(width="full")
+
+
+@app.cell
+def _():
+    import os
+    from pathlib import Path
+
+    import marimo as mo
+    import pandas as pd
+
+    from koobi.cards import load_card, save_card
+    from koobi.charts import measure_bar
+    from koobi.config import load_config
+    from koobi.index import build, connect, query_cards
+
+    return (
+        Path,
+        build,
+        connect,
+        load_card,
+        load_config,
+        measure_bar,
+        mo,
+        os,
+        pd,
+        query_cards,
+        save_card,
+    )
+
+
+@app.cell
+def _(Path, load_config, os):
+    config_hint = os.environ.get("KOOBI_CONFIG")
+    start_path = Path(config_hint).resolve() if config_hint else Path.cwd()
+    cfg = load_config(start_path)
+    return (cfg,)
+
+
+@app.cell
+def _(mo):
+    reindex_button = mo.ui.run_button(label="Reindex")
+    reindex_button
+    return (reindex_button,)
+
+
+@app.cell
+def _(build, cfg, connect, reindex_button):
+    # Referencing reindex_button.value makes this cell re-run when it is clicked.
+    # The index is rebuilt here (and on first load) so it never goes stale.
+    _reindex_tick = reindex_button.value
+    build(cfg)
+    con = connect(cfg)
+    return (con,)
+
+
+@app.cell
+def _(con):
+    projects = [
+        row[0]
+        for row in con.execute(
+            "SELECT DISTINCT project FROM cards ORDER BY project"
+        ).fetchall()
+    ]
+    statuses = [
+        row[0]
+        for row in con.execute(
+            "SELECT DISTINCT status FROM cards ORDER BY status"
+        ).fetchall()
+    ]
+    measures = [
+        row[0]
+        for row in con.execute(
+            "SELECT DISTINCT key FROM measures ORDER BY key"
+        ).fetchall()
+    ]
+    return measures, projects, statuses
+
+
+@app.cell
+def _(measures, mo, projects, statuses):
+    project_options = {"All projects": None}
+    project_options.update({name: name for name in projects})
+    status_options = {"All statuses": None}
+    status_options.update({name: name for name in statuses})
+
+    project_select = mo.ui.dropdown(
+        project_options, value="All projects", label="Project"
+    )
+    status_select = mo.ui.dropdown(
+        status_options, value="All statuses", label="Status"
+    )
+    search_text = mo.ui.text(value="", placeholder="search name or tags", label="Search")
+    measure_select = (
+        mo.ui.dropdown(measures, value=measures[0], label="Measure chart")
+        if measures
+        else None
+    )
+
+    _filters = [project_select, status_select, search_text]
+    if measure_select is not None:
+        _filters.append(measure_select)
+    mo.hstack(_filters, justify="start")
+    return measure_select, project_select, search_text, status_select
+
+
+@app.cell
+def _(con, project_select, query_cards, search_text, status_select):
+    cards_df = query_cards(
+        con,
+        project=project_select.value,
+        status=status_select.value,
+        search=search_text.value or None,
+    )
+    return (cards_df,)
+
+
+@app.cell
+def _(cards_df, measure_bar, measure_select, mo):
+    if measure_select is None or measure_select.value is None:
+        chart_view = mo.md("_No measures available to chart._")
+    else:
+        chart_view = mo.ui.altair_chart(measure_bar(cards_df, measure_select.value))
+    chart_view
+    return
+
+
+@app.cell
+def _(cards_df, mo):
+    table = mo.ui.table(cards_df, selection="multi", label="Models")
+    table
+    return (table,)
+
+
+@app.cell
+def _(Path, cards_df, cfg, load_card, mo, pd, table):
+    mo.stop(cards_df.empty, mo.md("No cards match the current filters."))
+
+    _selection = table.value if isinstance(table.value, pd.DataFrame) else pd.DataFrame()
+    if _selection.empty:
+        _selection = cards_df.head(1)
+
+    selected_id = str(_selection.iloc[0]["id"])
+    selected_row = cards_df[cards_df["id"] == selected_id].iloc[0]
+    card = load_card(Path(selected_row["path"]), root=cfg.root)
+
+    metadata_rows = (
+        [{"section": "metric", "key": k, "value": v} for k, v in card.metrics.items()]
+        + [{"section": "param", "key": k, "value": v} for k, v in card.params.items()]
+        + [{"section": "meta", "key": "tags", "value": ", ".join(card.tags)}]
+    )
+    metadata_df = pd.DataFrame(metadata_rows, columns=["section", "key", "value"])
+
+    _allowed_status = ["idea", "running", "candidate", "promoted", "archived"]
+    edit_form = mo.ui.form(
+        mo.ui.dictionary(
+            {
+                "name": mo.ui.text(value=card.name, label="Name"),
+                "status": mo.ui.dropdown(
+                    _allowed_status,
+                    value=card.status if card.status in _allowed_status else "candidate",
+                    label="Status",
+                ),
+                "tags": mo.ui.text(
+                    value=", ".join(card.tags), label="Tags (comma separated)"
+                ),
+                "body": mo.ui.text_area(value=card.body, label="Description", rows=10),
+            }
+        ),
+        submit_button_label="Save card",
+    )
+
+    mo.vstack(
+        [
+            mo.md(f"## {card.name}"),
+            mo.md(
+                f"**ID:** `{card.id}`  \n"
+                f"**Type:** `{card.type}`  \n"
+                f"**Project:** `{card.project}`  \n"
+                f"**Status:** `{card.status}`"
+            ),
+            mo.ui.table(metadata_df, selection=None, label="Measures / params"),
+            mo.md("### Description"),
+            mo.md(card.body or "_No description._"),
+            mo.md("### Edit card"),
+            edit_form,
+        ]
+    )
+    return card, edit_form
+
+
+@app.cell
+def _(build, card, cfg, edit_form, mo, save_card):
+    save_message = ""
+    if edit_form.value:
+        submitted = edit_form.value
+        card.name = str(submitted["name"])
+        card.status = str(submitted["status"])
+        card.tags = [tag.strip() for tag in str(submitted["tags"]).split(",") if tag.strip()]
+        card.body = str(submitted["body"])
+        save_card(card, fields=["name", "status", "tags", "body"])
+        build(cfg)
+        save_message = f"Saved `{card.id}`. Click **Reindex** to refresh the table."
+    mo.md(save_message)
+    return
+
+
+if __name__ == "__main__":
+    app.run()

koobi/cards.py

@@ -0,0 +1,106 @@
+"""Card filesystem operations."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from datetime import date
+from pathlib import Path
+from typing import Iterator
+
+from .schema import Card, SeriesRef, dump_card, parse_card
+
+HEADER_FIELDS = {
+    "id",
+    "name",
+    "type",
+    "project",
+    "status",
+    "created",
+    "updated",
+    "tags",
+    "metrics",
+    "params",
+    "artifacts",
+    "series",
+    "links",
+}
+
+
+def load_card(path: Path | str, *, root: Path | str | None = None) -> Card:
+    """Load a card from disk and resolve data paths against root."""
+    card_path = Path(path).resolve()
+    text = card_path.read_text(encoding="utf-8")
+    card = parse_card(text)
+    card.path = card_path
+    _resolve_paths(card, Path(root).resolve() if root is not None else card_path.parent)
+    return card
+
+
+def save_card(card: Card, *, fields: list[str] | None = None) -> None:
+    """Save a card while preserving untouched fields and body."""
+    if card.path is None:
+        raise ValueError("Card.path is required to save a card.")
+
+    target_path = card.path
+    original = parse_card(target_path.read_text(encoding="utf-8"))
+    original.path = target_path
+    to_write = deepcopy(original)
+
+    if fields is None:
+        to_write = deepcopy(card)
+    else:
+        for field_name in fields:
+            _copy_field(to_write, card, field_name)
+
+    to_write.updated = date.today()
+    if "updated" not in to_write.key_order:
+        to_write.key_order.append("updated")
+
+    rendered = dump_card(to_write)
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+    target_path.write_text(rendered, encoding="utf-8")
+    card.updated = to_write.updated
+
+
+def iter_cards(root: Path | str, *, loader_root: Path | str | None = None) -> Iterator[Card]:
+    """Recursively iterate all valid cards under root."""
+    cards_root = Path(root).resolve()
+    effective_root = Path(loader_root).resolve() if loader_root is not None else cards_root
+    if not cards_root.exists():
+        return
+
+    for path in sorted(cards_root.rglob("*.md")):
+        if path.name.startswith("_"):
+            continue
+        card = load_card(path, root=effective_root)
+        if not card.id:
+            continue
+        yield card
+
+
+def _resolve_paths(card: Card, root: Path) -> None:
+    card.resolved_artifacts = {}
+    for artifact_name, artifact_path in card.artifacts.items():
+        card.resolved_artifacts[artifact_name] = _resolve_path(root, artifact_path)
+
+    for ref in card.series.values():
+        if isinstance(ref, SeriesRef):
+            ref.abs_path = _resolve_path(root, ref.path)
+
+
+def _resolve_path(root: Path, raw_path: str) -> Path:
+    path = Path(raw_path)
+    if path.is_absolute():
+        return path
+    return (root / path).resolve()
+
+
+def _copy_field(target: Card, source: Card, field_name: str) -> None:
+    if field_name == "body":
+        target.body = source.body
+        return
+    if not hasattr(target, field_name):
+        raise ValueError(f"Unknown card field '{field_name}'.")
+    setattr(target, field_name, deepcopy(getattr(source, field_name)))
+    if field_name in HEADER_FIELDS and field_name not in target.key_order:
+        target.key_order.append(field_name)

koobi/charts.py

@@ -0,0 +1,30 @@
+"""Chart helpers for Koobi."""
+
+from __future__ import annotations
+
+import altair as alt
+import pandas as pd
+
+
+def measure_bar(cards_df: pd.DataFrame, measure: str) -> alt.Chart:
+    """Bar chart of one measure across card ids."""
+    if cards_df.empty or measure not in cards_df.columns:
+        empty = pd.DataFrame({"id": [], "value": []})
+        return (
+            alt.Chart(empty)
+            .mark_bar()
+            .encode(x=alt.X("id:N", title="Card"), y=alt.Y("value:Q", title=measure))
+            .properties(title=f"{measure} by card")
+        )
+
+    plot_df = cards_df[["id", measure]].copy().rename(columns={measure: "value"})
+    return (
+        alt.Chart(plot_df)
+        .mark_bar()
+        .encode(
+            x=alt.X("id:N", sort="-y", title="Card"),
+            y=alt.Y("value:Q", title=measure),
+            tooltip=["id:N", "value:Q"],
+        )
+        .properties(title=f"{measure} by card")
+    )

koobi/cli.py

@@ -0,0 +1,174 @@
+"""CLI entrypoint for Koobi."""
+
+from __future__ import annotations
+
+import argparse
+from datetime import date
+import os
+from pathlib import Path
+import subprocess
+import sys
+
+from .config import load_config
+from .index import build
+from .schema import Card, dump_card
+
+
+def main() -> int:
+    """Run the Koobi command-line interface."""
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    command = getattr(args, "command", None)
+    if command == "init":
+        return _cmd_init(args)
+    if command == "new":
+        return _cmd_new(args)
+    if command == "index":
+        return _cmd_index(args)
+    if command == "ui":
+        return _cmd_ui(args)
+
+    parser.print_help()
+    return 1
+
+
+def _resolve_config_start(args: argparse.Namespace) -> Path:
+    """Resolve where to start config discovery.
+
+    Precedence: explicit ``--config`` > ``KOOBI_CONFIG`` env var > current
+    working directory. The returned path is handed to ``load_config``, which
+    accepts either a ``koobi.toml`` file or a directory to search upward from.
+    """
+    config_arg = getattr(args, "config", None)
+    if config_arg is not None:
+        return config_arg.resolve()
+    env_config = os.environ.get("KOOBI_CONFIG")
+    if env_config:
+        return Path(env_config).resolve()
+    return Path.cwd()
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="koobi", description="Koobi Phase 0 CLI")
+    subparsers = parser.add_subparsers(dest="command")
+
+    init_parser = subparsers.add_parser("init", help="Create koobi.toml and cards directory")
+    init_parser.add_argument("--path", type=Path, default=Path.cwd(), help="Project root path.")
+
+    new_parser = subparsers.add_parser("new", help="Create a new card file")
+    new_parser.add_argument("card_id", help="Card id, for example demo_project.my_model")
+    new_parser.add_argument("--name", default=None, help="Card display name")
+    new_parser.add_argument("--type", default="model", help="Card type")
+    new_parser.add_argument("--project", default="default", help="Card project")
+    new_parser.add_argument("--status", default="idea", help="Card status")
+    new_parser.add_argument("--config", type=Path, default=None, help="Path to koobi.toml or project directory")
+
+    index_parser = subparsers.add_parser("index", help="Build the DuckDB index")
+    index_parser.add_argument("--config", type=Path, default=None, help="Path to koobi.toml or project directory")
+
+    ui_parser = subparsers.add_parser("ui", help="Launch the Marimo app")
+    ui_parser.add_argument("--config", type=Path, default=None, help="Path to koobi.toml or project directory")
+
+    return parser
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    root = args.path.resolve()
+    cards_dir = root / "docs" / "cards"
+    index_path = ".koobi/index.duckdb"
+    root.mkdir(parents=True, exist_ok=True)
+    cards_dir.mkdir(parents=True, exist_ok=True)
+
+    config_path = root / "koobi.toml"
+    if not config_path.exists():
+        config_path.write_text(
+            "\n".join(
+                [
+                    "[koobi]",
+                    'cards = "docs/cards"',
+                    'root = "."',
+                    f'index = "{index_path}"',
+                    "",
+                    "[display]",
+                    'primary_measures = ["sharpe", "calmar", "max_drawdown"]',
+                    'default_sort = "sharpe"',
+                    "packs = []",
+                    "",
+                ]
+            ),
+            encoding="utf-8",
+        )
+        print(f"Created {config_path}")
+    else:
+        print(f"Using existing {config_path}")
+
+    print(f"Cards directory: {cards_dir}")
+    return 0
+
+
+def _cmd_new(args: argparse.Namespace) -> int:
+    cfg = load_config(_resolve_config_start(args))
+    card = Card(
+        id=args.card_id,
+        name=args.name or args.card_id,
+        type=args.type,
+        project=args.project,
+        status=args.status,
+        created=date.today(),
+        updated=date.today(),
+        tags=[],
+        metrics={},
+        params={},
+        artifacts={},
+        series={},
+        links=[],
+        body="",
+        key_order=[
+            "id",
+            "name",
+            "type",
+            "project",
+            "status",
+            "created",
+            "updated",
+            "tags",
+            "metrics",
+            "params",
+            "artifacts",
+            "series",
+            "links",
+        ],
+    )
+    output_path = cfg.cards_root / f"{card.id}.md"
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(dump_card(card), encoding="utf-8")
+    print(f"Created {output_path}")
+    return 0
+
+
+def _cmd_index(args: argparse.Namespace) -> int:
+    cfg = load_config(_resolve_config_start(args))
+    path = build(cfg)
+    print(f"Built index at {path}")
+    return 0
+
+
+def _cmd_ui(args: argparse.Namespace) -> int:
+    config_target = _resolve_config_start(args)
+    cfg = load_config(config_target)
+    build(cfg)
+
+    app_path = Path(__file__).with_name("app.py")
+    env = dict(os.environ)
+    if cfg.config_path is not None:
+        env["KOOBI_CONFIG"] = str(cfg.config_path)
+    else:
+        env["KOOBI_CONFIG"] = str(config_target)
+
+    cmd = [sys.executable, "-m", "marimo", "run", str(app_path)]
+    return subprocess.run(cmd, env=env, check=False).returncode
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

koobi/config.py

@@ -0,0 +1,86 @@
+"""Configuration loading for Koobi."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+try:  # Python 3.11+
+    import tomllib
+except ModuleNotFoundError:  # Python 3.10 fallback
+    import tomli as tomllib
+
+
+@dataclass
+class Config:
+    """Runtime configuration resolved to absolute paths."""
+
+    root: Path
+    cards_root: Path
+    index: Path
+    primary_measures: list[str] = field(default_factory=list)
+    default_sort: str | None = None
+    packs: list[str] = field(default_factory=list)
+    config_path: Path | None = None
+
+
+def load_config(start: Path | str | None = None) -> Config:
+    """Load koobi.toml by searching upward, or use defaults if absent."""
+    start_path = Path(start).resolve() if start is not None else Path.cwd().resolve()
+    config_path = _find_config_path(start_path)
+    if config_path is None:
+        base = start_path if start_path.is_dir() else start_path.parent
+        return Config(
+            root=base,
+            cards_root=(base / "cards").resolve(),
+            index=(base / ".koobi" / "index.duckdb").resolve(),
+            primary_measures=[],
+            default_sort=None,
+            packs=[],
+            config_path=None,
+        )
+
+    data = tomllib.loads(config_path.read_text(encoding="utf-8"))
+    koobi_cfg = data.get("koobi", {})
+    display_cfg = data.get("display", {})
+    config_dir = config_path.parent
+
+    root = _resolve_config_path(config_dir, str(koobi_cfg.get("root", ".")))
+    cards_root = _resolve_config_path(config_dir, str(koobi_cfg.get("cards", "cards")))
+    index_path = _resolve_config_path(config_dir, str(koobi_cfg.get("index", ".koobi/index.duckdb")))
+
+    primary_measures = [str(v) for v in display_cfg.get("primary_measures", [])]
+    default_sort = display_cfg.get("default_sort")
+    packs = [str(v) for v in display_cfg.get("packs", [])]
+
+    return Config(
+        root=root,
+        cards_root=cards_root,
+        index=index_path,
+        primary_measures=primary_measures,
+        default_sort=str(default_sort) if default_sort is not None else None,
+        packs=packs,
+        config_path=config_path,
+    )
+
+
+def _find_config_path(start: Path) -> Path | None:
+    if start.is_file():
+        if start.name == "koobi.toml":
+            return start
+        current = start.parent
+    else:
+        current = start
+
+    for candidate_dir in [current, *current.parents]:
+        candidate = candidate_dir / "koobi.toml"
+        if candidate.exists():
+            return candidate.resolve()
+    return None
+
+
+def _resolve_config_path(base_dir: Path, raw_path: str) -> Path:
+    candidate = Path(raw_path)
+    if candidate.is_absolute():
+        return candidate.resolve()
+    return (base_dir / candidate).resolve()

koobi/index.py

@@ -0,0 +1,135 @@
+"""DuckDB indexing and query helpers."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import duckdb
+import pandas as pd
+
+from .cards import iter_cards
+from .config import Config
+
+
+def build(cfg: Config) -> Path:
+    """Rebuild the DuckDB index from card files.
+
+    Uses ``CREATE OR REPLACE TABLE`` rather than deleting the database file so a
+    rebuild is safe even when another connection to the same path is still open
+    in-process (DuckDB caches one database instance per path). This is what makes
+    the app's "Reindex" action reliable.
+    """
+    cfg.index.parent.mkdir(parents=True, exist_ok=True)
+
+    con = duckdb.connect(str(cfg.index))
+    try:
+        con.execute(
+            """
+            CREATE OR REPLACE TABLE cards(
+                id TEXT PRIMARY KEY,
+                name TEXT,
+                type TEXT,
+                project TEXT,
+                status TEXT,
+                created DATE,
+                updated DATE,
+                body TEXT,
+                path TEXT,
+                tags JSON
+            )
+            """
+        )
+        con.execute(
+            """
+            CREATE OR REPLACE TABLE measures(
+                card_id TEXT,
+                key TEXT,
+                value DOUBLE
+            )
+            """
+        )
+        con.execute(
+            """
+            CREATE OR REPLACE TABLE series_registry(
+                card_id TEXT,
+                name TEXT,
+                path TEXT,
+                x TEXT,
+                y JSON
+            )
+            """
+        )
+
+        for card in iter_cards(cfg.cards_root, loader_root=cfg.root):
+            con.execute("INSERT INTO cards VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)", card.row())
+            for key, value in card.metrics.items():
+                con.execute("INSERT INTO measures VALUES (?, ?, ?)", [card.id, key, float(value)])
+            for series_name, ref in card.series.items():
+                series_path = str(ref.abs_path) if ref.abs_path is not None else ref.path
+                con.execute(
+                    "INSERT INTO series_registry VALUES (?, ?, ?, ?, ?)",
+                    [card.id, series_name, series_path, ref.x, json.dumps(ref.y)],
+                )
+    finally:
+        con.close()
+    return cfg.index
+
+
+def connect(cfg: Config) -> duckdb.DuckDBPyConnection:
+    """Connect to index; build it first if needed."""
+    if not cfg.index.exists():
+        build(cfg)
+    return duckdb.connect(str(cfg.index))
+
+
+def query_cards(
+    con: duckdb.DuckDBPyConnection,
+    *,
+    project: str | None = None,
+    status: str | None = None,
+    search: str | None = None,
+    columns: list[str] | None = None,
+) -> pd.DataFrame:
+    """Return cards joined with wide-format measures."""
+    sql = (
+        "SELECT id, name, type, project, status, created, updated, body, path, tags "
+        "FROM cards WHERE 1=1"
+    )
+    params: list[Any] = []
+    if project:
+        sql += " AND project = ?"
+        params.append(project)
+    if status:
+        sql += " AND status = ?"
+        params.append(status)
+    if search:
+        sql += " AND (name ILIKE ? OR CAST(tags AS TEXT) ILIKE ?)"
+        term = f"%{search}%"
+        params.extend([term, term])
+
+    cards_df = con.execute(sql, params).fetchdf()
+    if cards_df.empty:
+        return cards_df
+
+    ids = cards_df["id"].tolist()
+    placeholders = ", ".join("?" for _ in ids)
+    measures_df = con.execute(
+        f"SELECT card_id, key, value FROM measures WHERE card_id IN ({placeholders})", ids
+    ).fetchdf()
+
+    if not measures_df.empty:
+        wide = (
+            measures_df.pivot_table(index="card_id", columns="key", values="value", aggfunc="first")
+            .reset_index()
+            .rename(columns={"card_id": "id"})
+        )
+        result = cards_df.merge(wide, on="id", how="left")
+    else:
+        result = cards_df
+
+    if columns:
+        selected = [col for col in columns if col in result.columns]
+        return result[selected]
+    return result

koobi/schema.py

@@ -0,0 +1,249 @@
+"""Card schema and Markdown frontmatter parsing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+RESERVED_KEYS = {
+    "id",
+    "name",
+    "type",
+    "project",
+    "status",
+    "created",
+    "updated",
+    "tags",
+    "metrics",
+    "params",
+    "artifacts",
+    "series",
+    "links",
+}
+
+
+@dataclass
+class SeriesRef:
+    """Series metadata stored in a card frontmatter."""
+
+    path: str
+    x: str | None = None
+    y: list[str] = field(default_factory=list)
+    abs_path: Path | None = None
+
+
+@dataclass
+class Card:
+    """Canonical card representation."""
+
+    id: str
+    name: str
+    type: str = "model"
+    project: str = "default"
+    status: str = "idea"
+    created: date | None = None
+    updated: date | None = None
+    tags: list[str] = field(default_factory=list)
+    metrics: dict[str, float] = field(default_factory=dict)
+    params: dict[str, Any] = field(default_factory=dict)
+    artifacts: dict[str, str] = field(default_factory=dict)
+    series: dict[str, SeriesRef] = field(default_factory=dict)
+    sections: dict[str, Any] = field(default_factory=dict)
+    links: list[str] = field(default_factory=list)
+    body: str = ""
+    path: Path | None = None
+    key_order: list[str] = field(default_factory=list)
+    resolved_artifacts: dict[str, Path] = field(default_factory=dict)
+
+    def row(self) -> tuple[str, str, str, str, str, str | None, str | None, str, str, str]:
+        """Return the exact cards-table tuple shape in technical design."""
+        if self.path is None:
+            raise ValueError("Card path is required to emit a cards row.")
+        return (
+            self.id,
+            self.name,
+            self.type,
+            self.project,
+            self.status,
+            _iso(self.created),
+            _iso(self.updated),
+            self.body,
+            str(self.path),
+            json.dumps(self.tags),
+        )
+
+
+def parse_card(text: str) -> Card:
+    """Parse Markdown card text into a Card dataclass."""
+    metadata, body = _split_frontmatter(text)
+    key_order = list(metadata.keys())
+
+    series_map: dict[str, SeriesRef] = {}
+    raw_series = metadata.get("series") or {}
+    if isinstance(raw_series, dict):
+        for name, payload in raw_series.items():
+            if not isinstance(payload, dict):
+                continue
+            raw_y = payload.get("y") or []
+            y_values = [str(item) for item in raw_y] if isinstance(raw_y, list) else [str(raw_y)]
+            series_map[str(name)] = SeriesRef(
+                path=str(payload.get("path", "")),
+                x=str(payload["x"]) if payload.get("x") is not None else None,
+                y=y_values,
+            )
+
+    raw_metrics = metadata.get("metrics") or {}
+    metrics: dict[str, float] = {}
+    if isinstance(raw_metrics, dict):
+        for metric_name, metric_value in raw_metrics.items():
+            metrics[str(metric_name)] = float(metric_value)
+
+    params = metadata.get("params") or {}
+    artifacts = metadata.get("artifacts") or {}
+    sections = {k: v for k, v in metadata.items() if k not in RESERVED_KEYS}
+
+    return Card(
+        id=str(metadata.get("id", "")),
+        name=str(metadata.get("name", "")),
+        type=str(metadata.get("type", "model")),
+        project=str(metadata.get("project", "default")),
+        status=str(metadata.get("status", "idea")),
+        created=_parse_date(metadata.get("created")),
+        updated=_parse_date(metadata.get("updated")),
+        tags=_coerce_str_list(metadata.get("tags", [])),
+        metrics=metrics,
+        params=params if isinstance(params, dict) else {},
+        artifacts={str(k): str(v) for k, v in artifacts.items()} if isinstance(artifacts, dict) else {},
+        series=series_map,
+        sections=sections,
+        links=_coerce_str_list(metadata.get("links", [])),
+        body=body,
+        key_order=key_order,
+    )
+
+
+def dump_card(card: Card) -> str:
+    """Serialize a Card into Markdown with YAML frontmatter."""
+    metadata = _serialize_card(card)
+    order = _metadata_order(card, metadata)
+    ordered_meta = {key: metadata[key] for key in order if key in metadata}
+    yaml_text = yaml.safe_dump(ordered_meta, sort_keys=False, default_flow_style=False).rstrip()
+    return f"---\n{yaml_text}\n---\n{card.body}"
+
+
+def _split_frontmatter(text: str) -> tuple[dict[str, Any], str]:
+    lines = text.splitlines(keepends=True)
+    if not lines or lines[0].strip() != "---":
+        return {}, text
+
+    end_idx = None
+    for idx, line in enumerate(lines[1:], start=1):
+        if line.strip() == "---":
+            end_idx = idx
+            break
+    if end_idx is None:
+        raise ValueError("Malformed frontmatter: missing closing '---'.")
+
+    header = "".join(lines[1:end_idx])
+    body = "".join(lines[end_idx + 1 :])
+    loaded = yaml.safe_load(header) or {}
+    if not isinstance(loaded, dict):
+        raise ValueError("Card frontmatter must be a mapping.")
+    return loaded, body
+
+
+def _serialize_card(card: Card) -> dict[str, Any]:
+    metadata: dict[str, Any] = {}
+    metadata["id"] = card.id
+    metadata["name"] = card.name
+    if "type" in card.key_order or card.type != "model":
+        metadata["type"] = card.type
+    if "project" in card.key_order or card.project != "default":
+        metadata["project"] = card.project
+    if "status" in card.key_order or card.status != "idea":
+        metadata["status"] = card.status
+    if "created" in card.key_order or card.created is not None:
+        metadata["created"] = _iso(card.created)
+    if "updated" in card.key_order or card.updated is not None:
+        metadata["updated"] = _iso(card.updated)
+    if "tags" in card.key_order or card.tags:
+        metadata["tags"] = list(card.tags)
+    if "metrics" in card.key_order or card.metrics:
+        metadata["metrics"] = {k: float(v) for k, v in card.metrics.items()}
+    if "params" in card.key_order or card.params:
+        metadata["params"] = card.params
+    if "artifacts" in card.key_order or card.artifacts:
+        metadata["artifacts"] = {k: str(v) for k, v in card.artifacts.items()}
+    if "series" in card.key_order or card.series:
+        metadata["series"] = {
+            name: {
+                "path": ref.path,
+                "x": ref.x,
+                "y": list(ref.y),
+            }
+            for name, ref in card.series.items()
+        }
+    if "links" in card.key_order or card.links:
+        metadata["links"] = list(card.links)
+    for section_key, section_value in card.sections.items():
+        metadata[section_key] = section_value
+    return metadata
+
+
+def _metadata_order(card: Card, metadata: dict[str, Any]) -> list[str]:
+    default_order = [
+        "id",
+        "name",
+        "type",
+        "project",
+        "status",
+        "created",
+        "updated",
+        "tags",
+        "metrics",
+        "params",
+        "artifacts",
+        "series",
+        "links",
+    ]
+    seen: set[str] = set()
+    order: list[str] = []
+
+    for key in card.key_order or default_order:
+        if key in metadata and key not in seen:
+            seen.add(key)
+            order.append(key)
+
+    for key in metadata.keys():
+        if key not in seen:
+            seen.add(key)
+            order.append(key)
+
+    return order
+
+
+def _parse_date(value: Any) -> date | None:
+    if value is None:
+        return None
+    if isinstance(value, date):
+        return value
+    return date.fromisoformat(str(value))
+
+
+def _iso(value: date | None) -> str | None:
+    if value is None:
+        return None
+    return value.isoformat()
+
+
+def _coerce_str_list(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return [str(item) for item in value]
+    return [str(value)]

koobi-0.0.1.dist-info/METADATA

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: koobi
+Version: 0.0.1
+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
+Requires-Dist: duckdb
+Requires-Dist: marimo
+Requires-Dist: pandas
+Requires-Dist: pyarrow
+Requires-Dist: python-frontmatter
+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="active")
+
+# 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 = "shipped"
+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.

koobi-0.0.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+koobi/__init__.py,sha256=nD7-cGqDqO7hpOHzARpsYwbtZp3IAoCyAiOpYcEKkzo,846
+koobi/app.py,sha256=bM_AspqkZ5u02at_5VvX5wGKsrTt11MWT74c7NVyxM0,6220
+koobi/cards.py,sha256=wqLLxqwFvozULj0hdYVQ-vUvM5AyvkelASNjh2Cyg9Y,3219
+koobi/charts.py,sha256=llbl2Oc_qheQeMSqXHl-ds2tEZksHesWmnRXHZGA7rE,927
+koobi/cli.py,sha256=2v8Y7oLIoLWxwHVqISZEvaYUEsviuGl6aGpYPEJ81HU,5425
+koobi/config.py,sha256=K9tV2rfdrt1r6uQqOqblwemWp-fFzOpDRumrzyN1ysU,2770
+koobi/index.py,sha256=JOr_y712Xa3Ap0uEXLLo6G_AmfSWpzCJ7PFJkvILWKY,4038
+koobi/schema.py,sha256=AYnqwPpbXO77oL64XEsURZ-ZtbvV2e8Em8cSBX9_3p4,7844
+koobi-0.0.1.dist-info/licenses/LICENSE,sha256=DFNTqoZ1aQLmIomIs7YhzhiZvMrGKkh-Ri7Mq08hx00,1066
+koobi-0.0.1.dist-info/METADATA,sha256=n9oNgUD-xWPzWO9QbW3lR8-Nxuj_ZO8wmP3h-3aYOZw,6193
+koobi-0.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+koobi-0.0.1.dist-info/entry_points.txt,sha256=12qqWPg-YGv98DslZJXliiRnmWG-Qk_q5KWzcdZ39hQ,41
+koobi-0.0.1.dist-info/top_level.txt,sha256=id_nUg0qDMmJBPQtLsyswEsJ-EGh5VllDg1xq2fSJ4k,6
+koobi-0.0.1.dist-info/RECORD,,

koobi-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

koobi-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+koobi = koobi.cli:main

koobi-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 blu3c0ral
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

koobi-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+koobi