Metadata-Version: 2.4
Name: goodseed
Version: 0.2.0
Summary: ML experiment tracker with local-first durability
Author: Goodseed Team
License-Expression: MIT
Keywords: experiment-tracking,machine-learning,mlops
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: httpx>=0.25.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: examples
Requires-Dist: scikit-learn>=1.0.0; extra == 'examples'
Requires-Dist: torch>=2.0.0; extra == 'examples'
Description-Content-Type: text/markdown

# Goodseed

ML experiment tracker. Logs metrics and configs to local SQLite files, serves them via a built-in HTTP server, and visualizes them in the browser.

## Install

```bash
cd goodseed
pip install -e .
```

For development:
```bash
pip install -e ".[dev]"
```

## Quick Start

```python
import goodseed

with goodseed.Run(experiment_name="my-experiment") as run:
    run.log_configs({"learning_rate": 0.001, "batch_size": 32})

    for step in range(100):
        loss = train_step()
        run.log_metrics({"loss": loss}, step=step)
```

Then view your runs:

```bash
goodseed serve
```

## How It Works

Each `Run()` creates a SQLite file at `~/.goodseed/projects/<project>/runs/<run_name>.sqlite`. Metrics and configs are written there during training. After the run closes, the WAL is checkpointed so the result is a single `.sqlite` file.

The `goodseed serve` command starts a local HTTP server that reads these files and exposes a JSON API. The frontend at [goodseed.ai](https://goodseed.ai/app/local) connects to this server to display your runs.

## Configuration

| Variable | Description |
|----------|-------------|
| `GOODSEED_HOME` | Data directory (default: `~/.goodseed`) |
| `GOODSEED_PROJECT` | Default project name (default: `default`) |

## CLI

```bash
goodseed                   # Start the server (default command)
goodseed serve [dir]       # Start the server, optionally from a specific directory
goodseed serve --port 9000 # Use a custom port
goodseed list              # List local runs
```

## Tests

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

See [DOCS.md](DOCS.md) for architecture details and API reference.
