Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

Songe: a bed on the moon, and the command pip install songe

A training engine for your local model, using your idle compute.

Install • How it works • Commands • Roadmap • Website

PyPI version Python versions License: Apache-2.0

Use your local model as usual through opencode, pi or any OpenAI-compatible tool. While you work, Songe notices what happens after each of the model's actions: the tool result, the error, your next message. When your agent is quiet, it teaches the model to see those coming. A new version is used only if it passes its checks, and nothing ever leaves your machine.

✨ Highlights

  • Learns from how you work. Your corrections, stated preferences and the tools' errors become lessons for your own model.
  • Two kinds of Dreams. A Quick Dream adds your preferences to the model's instructions in minutes; a Deep Dream trains the model itself while you are away.
  • Safe by default. A new version is used only if it does better on your own conversations; one click goes back to any earlier version.
  • Stays out of the way. Runs only when your agent is quiet, memory is free and the battery is fine, and stops the moment you are back.
  • Private. No account, no telemetry, no cloud. Songe never runs your tools.

📥 Install

With uv or pipx (Python 3.11 or later):

uv tool install songe        # or: pipx install songe
songe init

macOS with Homebrew:

brew tap sous-labs/tap
brew trust sous-labs/tap     # newer Homebrew asks this once
brew install songe
songe init

songe init finds your model server and your agents, shows what it will change, and asks once:

$ songe init

  Models    3 from LM Studio, each as songe/…
  Agent     opencode → Songe models · default songe/granite-4.2-3b-MLX-4bit
  Agent     pi → Songe models · choose one with /model
  Data      ~/Library/Application Support/songe
  Service   starts at login
  Learning  new conversations · starts when idle
  Replace   loaded copy when a better version is ready

Install? (Y/n)

Then pick a songe/… model in your agent, and work as usual.

Plain pip, and what you need

pip install songe works inside a virtual environment; outside one, Homebrew's and most Linux distributions' Python refuse it.

You need a model served locally, and an agent:

Supported Tested end to end
Model servers LM Studio, vLLM, Ollama, llama.cpp, mlx-lm LM Studio (macOS), vLLM (Linux)
Agents opencode and pi (set up for you); any OpenAI-compatible tool opencode, pi
Training Apple Silicon (MLX); NVIDIA and AMD (PyTorch) Apple Silicon, NVIDIA

Machines without a GPU still serve and record, but do not train. Tried Songe on another setup? Share the result on the testing board.

🌙 How it works

 your agent ──► Songe (127.0.0.1:7613) ──► your model server
                   │ records what happened
                   ▼
            when you are away: a Dream
   read lessons ─► practice ─► train ─► check ─► use only if better
Quick Dream Deep Dream
Takes a few minutes an hour or more
Does adds the preferences you stated or showed to the model's instructions writes practice from your lessons and trains a small adapter on it
You see each new preference, with a before/after where the answer changes why the new version was or was not used
Undo undo the Quick Dream, or remove one preference go back to any earlier version

With auto-dream on, Dreams start when your agent has been quiet for a while. Or press Dream in the dashboard (songe open). A Dream never just disappears: it keeps going on the page, or says why it stopped.

How it learns, in more detail
  • 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, and 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.

Before the first training Songe measures how much your computer can learn at once, and trains on what fits. See DESIGN.md.

⌨️ Commands

Command What it does
songe what it is doing
songe open the dashboard in your browser
songe models each model, and whether it dreams on its own
songe models MODEL on|off auto-dream for one model
songe sleep start a Deep Dream now
songe undo MODEL go back one version
songe pause / songe resume stop and restart learning
songe doctor check the setup
songe forget delete recorded conversations (learned versions stay)
songe uninstall stop the service and restore your agent settings
What it changes on your machine
  • 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. Your own models are never touched.
  • One provider entry in opencode and pi, with a backup.
  • A background service that starts at login.
Upgrade and remove

uv tool upgrade songe, pipx upgrade songe or brew upgrade 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.

🧭 Roadmap and contributing

Where Songe is going: ROADMAP.md. Ideas and bugs are welcome as issues; to contribute, see CONTRIBUTING.md. Security reports: SECURITY.md.

Licensed under Apache-2.0.

Metadata

Release files for songe 0.1.0a14

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for songe 0.1.0a14
File Size Uploaded Provenance Actions
songe-0.1.0a14.tar.gz 843.8 kB With provenance Details for songe-0.1.0a14.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for songe 0.1.0a14
File Interpreter ABI Platform Actions
songe-0.1.0a14-py3-none-any.whl Python 3 none any Details for songe-0.1.0a14-py3-none-any.whl

Total release size: 1.4 MB

Release files / songe-0.1.0a14.tar.gz

Download URL songe-0.1.0a14.tar.gz
Size 843.8 kB
Tags Source
SHA-256 checksum
How to use checksums
2c15c5d36ec17521655118704267b7ea83989c37e629ba45e326825c93663a2d
BLAKE2b-256 checksum
How to use checksums
552c402a5a725d71cfa38907761939f880d378a39411185456b8690a91a3e9d4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / songe-0.1.0a14-py3-none-any.whl

Download URL songe-0.1.0a14-py3-none-any.whl
Size 507.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
35632eb2dc54acf1b472634c1cb1ad419515b6832c577db3726f7b5d70484c95
BLAKE2b-256 checksum
How to use checksums
6a0ea14e88df336dcd0328dd76936f3ef05e995b63a6da1dfc95d201a8a96206
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for songe 0.1.0a14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for songe-0.1.0a14.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page