koobi 0.0.1__tar.gz

koobi-0.0.1/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,202 @@
+# 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/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "koobi"
+version = "0.0.1"
+description = "File-native model and experiment registry"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "blu3c0ral", email = "blu3c0ral@protonmail.ch" }]
+keywords = ["experiment-tracking", "model-registry", "marimo", "duckdb", "markdown"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Operating System :: OS Independent",
+  "Topic :: Scientific/Engineering",
+]
+dependencies = [
+  "altair",
+  "duckdb",
+  "marimo",
+  "pandas",
+  "pyarrow",
+  "python-frontmatter",
+  "tomli; python_version < '3.11'",
+]
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.urls]
+Homepage = "https://github.com/blu3c0ral/koobi"
+Repository = "https://github.com/blu3c0ral/koobi"
+Issues = "https://github.com/blu3c0ral/koobi/issues"
+
+[project.scripts]
+koobi = "koobi.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

koobi-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

koobi-0.0.1/src/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",
+]