youparle

Local tooling for a YouParle language learning vault.

A student learns a language with an LLM agent that lives in a folder on their machine. This package is what that agent calls for everything it is not allowed to do by itself: publishing lessons and cards, rendering exercises, fetching media and what sources answer, showing the student a picture or a sound. There is no server and no account. No data leaves the machine, unless the student chooses a voice or a transcription that works over the network: the agent says so when it offers one.

The package also makes that folder. youparle init copies a template that ships inside the package, src/youparle/vault_template/: the agent's instructions and the Obsidian settings with the Spaced Repetition plugin. After that the folder belongs to the student. The one part the package rewrites is the youparle block at the top of AGENTS.md, which holds the agent's instructions; the student writes their own below it. The package recognises a vault by its contents alone: AGENTS.md and agent/ at the root.

Installing

The student's agent installs youparle. The student opens an empty folder in their harness and pastes the prompt in INSTALL.md. An agent that cannot run commands on the student's computer, such as a chat on the web, stops there and says where to go instead. Otherwise the agent installs uv the way its system needs, then youparle with uv tool install, and runs youparle init in that folder. It asks the student to install Obsidian and open the folder in it, runs youparle check, sets a hook that runs youparle guide when a session starts if the harness has hooks, and asks them to restart the harness. No administrator rights are needed.

By hand, from the course folder:

uv tool install --managed-python --python 3.13 youparle
uv tool update-shell
youparle init

init also takes a path. The folder must be empty, or must not exist yet. Hidden files a harness, Obsidian or the system made there are allowed, but not .git. Run init again in a vault, and it creates only what is missing and rewrites the youparle block in AGENTS.md. Any other folder is refused: for init, a vault is a folder whose AGENTS.md holds that block.

Then, from the course folder:

youparle check

To update, ask the agent. It follows youparle skill update: it stops the server, runs uv tool upgrade youparle, then youparle init to rewrite the block, then youparle check.

Once a day, youparle guide looks in the background for a newer release on PyPI. At the start of a later session, the agent tells the student in one sentence that an update is available, and goes on with the course.

Installing youparle installs no voice and no way to transcribe sounds. The agent offers them when it meets the student, with the voice and transcription skills: the Microsoft voice, a service or a program of the student's own, or none. It writes the scripts itself, in agent/scripts/, and youparle runs none of them. See docs/scripts.md.

Commands

Every command but init resolves its vault from the current directory, and every command takes --json. A refusal says what was refused and what to do instead, on stderr, with a non-zero exit code.

youparle guide and youparle skill are what the agent is told, and they ship with the code, so they cannot describe a version that is not installed. youparle <command> --help has the options.

Documentation

docs/ explains why the package is built the way it is, and which rules a change must not break. Start at docs/README.md.

Developing

uv sync --group dev
uv run pytest
uv run ruff check . && uv run ruff format --check .

Everything in this repository is in English — names, comments, tests and the messages the CLI prints. The system is agnostic about the language being taught, and French is only one course among others.

A running server holds the code it was started with, so run youparle server stop after changing anything it serves.

What a new vault holds is the folder src/youparle/vault_template/. See docs/vault.md before changing it.

Licence

MIT. See LICENSE.

The vault template includes the Obsidian plugin Spaced Repetition by Stephen Mwangi, under the MIT licence. Its main.js bundles other libraries, all MIT except minimatch, which is under the Blue Oak Model License 1.0.0. The plugin's folder, src/youparle/vault_template/.obsidian/plugins/obsidian-spaced-repetition/, holds its LICENSE and a THIRD-PARTY-NOTICES.txt with the licence of each bundled library, so both reach every vault.