Metadata-Version: 2.5
Name: songe
Version: 0.1.0a9
Summary: Local hindsight distillation for a model that sleeps.
Project-URL: Homepage, https://github.com/sous-labs/songe
Project-URL: Repository, https://github.com/sous-labs/songe
Project-URL: Issues, https://github.com/sous-labs/songe/issues
Author: Sous Labs
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: bashlex<1,>=0.18
Requires-Dist: gguf<1,>=0.19
Requires-Dist: httpx<1,>=0.28
Requires-Dist: jsonschema<5,>=4.26
Requires-Dist: lmstudio<2,>=1.5
Requires-Dist: mlx-lm<0.33,>=0.32; sys_platform == 'darwin' and platform_machine == 'arm64'
Requires-Dist: mlx<0.33,>=0.32.4; sys_platform == 'darwin' and platform_machine == 'arm64'
Requires-Dist: packaging<27,>=24.2
Requires-Dist: psutil<8,>=5.9
Requires-Dist: rich<16,>=15
Requires-Dist: starlette<2,>=0.49
Requires-Dist: textual<7,>=6.12
Requires-Dist: uvicorn<1,>=0.38
Provides-Extra: cuda
Requires-Dist: accelerate<2,>=1; extra == 'cuda'
Requires-Dist: bitsandbytes<1,>=0.45; (sys_platform == 'linux' or sys_platform == 'win32') and extra == 'cuda'
Requires-Dist: nvidia-ml-py>=12; (sys_platform == 'linux' or sys_platform == 'win32') and extra == 'cuda'
Requires-Dist: peft<1,>=0.21; extra == 'cuda'
Requires-Dist: protobuf<8,>=5; extra == 'cuda'
Requires-Dist: safetensors<1,>=0.5; extra == 'cuda'
Requires-Dist: sentencepiece<1,>=0.2; extra == 'cuda'
Requires-Dist: torch<3,>=2.11; extra == 'cuda'
Requires-Dist: transformers<6,>=5.22.2; extra == 'cuda'
Provides-Extra: mlx
Requires-Dist: mlx-lm<0.33,>=0.32; (sys_platform == 'darwin' and platform_machine == 'arm64') and extra == 'mlx'
Requires-Dist: mlx<0.33,>=0.32.4; (sys_platform == 'darwin' and platform_machine == 'arm64') and extra == 'mlx'
Provides-Extra: rocm
Requires-Dist: accelerate<2,>=1; extra == 'rocm'
Requires-Dist: peft<1,>=0.21; extra == 'rocm'
Requires-Dist: protobuf<8,>=5; extra == 'rocm'
Requires-Dist: safetensors<1,>=0.5; extra == 'rocm'
Requires-Dist: sentencepiece<1,>=0.2; extra == 'rocm'
Requires-Dist: torch<3,>=2.11; extra == 'rocm'
Requires-Dist: transformers<6,>=5.22.2; extra == 'rocm'
Provides-Extra: torch
Requires-Dist: accelerate<2,>=1; extra == 'torch'
Requires-Dist: peft<1,>=0.21; extra == 'torch'
Requires-Dist: protobuf<8,>=5; extra == 'torch'
Requires-Dist: safetensors<1,>=0.5; extra == 'torch'
Requires-Dist: sentencepiece<1,>=0.2; extra == 'torch'
Requires-Dist: torch<3,>=2.11; extra == 'torch'
Requires-Dist: transformers<6,>=5.22.2; extra == 'torch'
Description-Content-Type: text/markdown

# Songe

A local model that sleeps.

You use your model as usual, through opencode, pi or any OpenAI-compatible tool. When your computer is idle and on power, Songe reads back what happened after each of the model's actions — the tool result, the error, your next message — and teaches the model to anticipate it. After a candidate passes the checks, the same model name serves that version. Nothing leaves your machine.

## How it learns

The only new information a local model ever gets is what happened *after* it acted. Given that hindsight, the same model can usually tell what it should have done; without it, it can't. Songe closes that gap:

- **Teacher**: the model as it was when the cycle began, shown the conversation *and* what happened next.
- **Student**: the model with a small LoRA adapter, shown only the conversation.
- The student writes its own answers and the teacher scores them token by token (on-policy distillation, as in Google DeepMind's GKD). The student learns where it was wrong, in its own words, so it forgets little.
- Each cycle trains every new usable step once, mixed with replay of earlier steps and general anchors so old skills stay.
- It continues the current adapter with replay, rebuilding from the original base when experience is forgotten or the base, tools, or accumulated drift require it.
- A new version is served only if it is measurably better on conversations it never trained on and not measurably worse at general tasks. Otherwise nothing changes.

Songe never runs your tools at night. It only reads what already happened.

## Requirements

- Apple Silicon with MLX, Linux with NVIDIA or AMD, or Windows with NVIDIA.
- A locally accessible model served by LM Studio, Ollama, llama.cpp, mlx-lm, or vLLM.
- Python 3.11 or later for pip installation; Homebrew supplies Python 3.12.

Memory and training support are measured on your machine. CPU-only machines can serve and record experience. Calibration must complete before learning starts.

## Install

```sh
brew install sous-labs/tap/songe
pip install songe
songe init
```

`songe init` finds your model server and agents, shows a short facts list, and asks once. Use `--show-diff` for exact dependency commands and config diffs, or `--yes` to accept the plan in a script. It exposes your models through the Songe provider. Pick a model in your agent as usual; Songe follows each one you use. Training support and memory are measured during idle gaps. `--model PATH` optionally pre-enables a local base. Existing single-model installs retain their versions and undo history.

Choose Homebrew or pip, then run `songe init`. In opencode, a local default model switches to its Songe entry automatically. In pi, choose a `songe/…` model with `/model`. `songe open` shows each model's Flow (what Songe is doing now) and the raw steps it learns from.

| Platform | Dependencies | CI scope |
| --- | --- | --- |
| macOS Apple Silicon | MLX and MLX-LM install automatically | Python 3.12 tests on `main` and `v*` tags; Metal tests skip when unavailable |
| Linux NVIDIA / AMD | `init` installs missing training dependencies in its private environment | Ubuntu Python 3.11/3.12 CPU tests; GPU training unverified |
| Windows NVIDIA | `init` selects PyTorch wheels for the detected driver | Portable locks and services implemented; Windows GPU validation required |

The default Linux/Windows install contains the proxy, store, CLI, web assets and
Textual dependency without an ML framework. Init detects the accelerator and
plans any missing training stack. CPU tests cover the Torch pipeline; accelerator
and live server validation still require real hardware.
See [accelerator installation and CI limits](docs/RELEASING.md#accelerator-installation).

## Use

There is nothing to do. When you want to look:

```sh
songe          # where things stand, in one block
songe open     # now, next, models and learning results
songe models   # learning levels, support reasons, and pending data
songe models MODEL off
songe models MODEL new
songe models MODEL all
songe undo MODEL  # restore this model's previous version
```

Also: `songe pause`, `songe resume`, `songe sleep --now`, `songe forget` (delete what it has seen), `songe uninstall`.

## The dashboard

`songe open` starts with `now`, `next`, and `paused`, followed by the Learning switch. They show the current model and work, measured progress and ETA when available, the next action and its condition, or a concrete waiting reason. The models table groups formats into one row with expandable files, followed by learning summaries and retained versions. Returning to a retained version loads and checks its weights before switching.

The browser paints the last state from session storage while fetching. Polls use ETags and separate status, models, learning, and versions revisions; unchanged sections retain their controls, focus, and expanded details. Static assets use content hashes and long-term caching. The dashboard is local.

## What it changes on your machine

- Private data under the platform's application data directory: macOS `~/Library/Application Support/songe`, Linux `$XDG_DATA_HOME/songe`, or Windows `%LOCALAPPDATA%\songe`.
- LM Studio's models folder: a `songe/` folder holding the current and previous learned versions. Your existing models are never touched.
- opencode and pi: one added provider entry each, with a backup. `songe uninstall` restores them.
- A per-user background service through launchd, systemd, or Windows Task Scheduler.

It sends no notifications and needs no account. `songe uninstall --purge` removes everything it created and keeps any other files in its data directory.

## When it sleeps

Each model has three learning levels: **off** forwards and records without training; **new** (the default) learns only from exchanges recorded after that model's level was set; **all** also learns from earlier shared experience, including exchanges with other models. Switching back to new starts a fresh window. Scoring, on-policy sampling, training and held-out checks are per model. Songe trains one model at a time, choosing the most eligible pending experience, then the least recently trained. The GUI and TUI offer the same three choices. Existing on/off installs migrate to new/off while preserving versions and undo.

During idle gaps without proxy traffic, with adequate memory, power, a safe temperature, and new learnable experience. There is no daily time limit: Songe scores all new experience, trains the selected new pool once plus replay and anchors, then checks and switches the version if it passes. New data starts the next cycle; it never repeats a pool to fill time. Work starts after ten seconds without proxy traffic. The moment you come back it stops, saves its place, and continues later. A MacBook with its lid closed sleeps too, so learning waits for the next time it is open and idle.

---

Technical details, configuration and the development workflow: [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md). Design and first principles: [DESIGN.md](DESIGN.md).

Songe stops or unloads only work it started. Existing user model instances remain
resident; learning waits when they leave too little memory. For llama.cpp and
vLLM, init provisions a separate loopback endpoint for Songe’s own server. Before each learning slice, Songe sizes context, responses, logit chunks and serial microbatches from live memory and calibration. Observed pressure transitions set the RAM margin; the live guard remains the hard stop.
