Metadata-Version: 2.5
Name: songe
Version: 0.1.0a13
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
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
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 bed on the moon, and the command pip install songe](https://souslabs.ai/assets/songe-share-v1.png)](https://souslabs.ai/songe)

# Songe

A local model that learns from how you use it.

Use your model as usual through opencode, pi or any OpenAI-compatible tool. When your agent is quiet, Songe looks at what happened after each of the model's actions — the tool result, the error, your next message — and teaches the model to see it coming. A new version is used only if it passes checks. Nothing leaves your machine.

## Install

macOS with Homebrew:

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

Or with pip (Python 3.11 or later; with Homebrew's Python use `pipx install songe`):

```sh
pip install songe
songe init
```

`songe init` finds your model server and your agents, shows what it will change, and asks once. Then pick a `songe/…` model in your agent. In opencode, a local default model switches over automatically.

Needs a model served locally by LM Studio, Ollama, llama.cpp, mlx-lm or vLLM. Learning runs on Apple Silicon (MLX); Linux and Windows with NVIDIA or AMD are supported but less tested. Machines without a GPU still serve and record.

## Use

Use your agent as usual. Songe learns in **Dreams**:

- **Quick Dream** (a few minutes): reads your newest conversations and adds
  the preferences you stated or showed ("always use pnpm", "put my name at
  the top of the script") to the model's instructions right away. It shows
  what it added, with a before/after where the answer changes.
- **Deep Dream** (an hour or more): writes practice from those lessons,
  trains a small adapter on it, and checks the result on your conversations
  before using it. If it is not clearly better, nothing changes, and the
  report says why.

With **auto-dream** on, Dreams start when your agent has been quiet for a
while and stop the moment you use it again. Or press **Dream** in the
dashboard. A Dream never just disappears: it keeps going on the page or
says why it stopped.

```sh
songe          # what it is doing
songe open     # dashboard in your browser
songe models   # each model, and whether it dreams on its own
```

To change things:

```sh
songe models MODEL on|off   # auto-dream for one model
songe undo MODEL            # go back one version
songe pause
songe resume
songe sleep                 # start a Deep Dream now
songe doctor                # check the setup
songe forget                # delete recorded conversations (learned versions stay)
```

## How it learns

- **Reading.** Songe reads each conversation for the moments that teach
  something: your corrections and stated rules, retries, tool errors.
- **Practice.** For each lesson your model writes short practice scenes in
  your agent's own tools. Your real conversations are never trained on.
- **Training.** The model as it was, shown the lesson, is the teacher; the
  same model with a small adapter, shown only the scene, is the student
  (on-policy distillation). Earlier skills are rehearsed so they stay.
- **Checking.** At the moments you reacted to, the version in use and the
  new one each answer; a judge compares what they do. The new version is
  used only if it does clearly better, does not change what already worked,
  and its answers stay healthy.

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

## When it runs

Only when your agent is quiet, there is enough free memory, the battery is
not low and the machine is cool. Before the first training Songe measures
how much your computer can learn at once. When you come back it stops at
once, saves its place and continues later.

## What it changes

- Its data folder: `~/Library/Application Support/songe` on macOS, `$XDG_DATA_HOME/songe` on Linux, `%LOCALAPPDATA%\songe` on Windows.
- A `songe/` folder in LM Studio's models folder with the current learned version. Older versions are rebuilt when you return to them. Your own models are never touched.
- One provider entry in opencode and pi, with a backup.
- A background service that starts at login.

No account, no notifications.

## Upgrade and remove

`brew upgrade songe` or `pip install -U songe`: the service moves to the new version by itself in a quiet moment.

`songe uninstall` stops the service and restores your agent settings; add `--purge` to also delete its data and learned versions. Run it before `brew uninstall songe`.

---

Details and development: [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md). Design: [DESIGN.md](DESIGN.md).

## License

[Apache-2.0](LICENSE).
