Metadata-Version: 2.5
Name: youparle
Version: 0.1.1
Summary: Local tooling for a YouParle language learning vault
Project-URL: Homepage, https://gitlab.com/franckbrl/youparle
Project-URL: Source, https://gitlab.com/franckbrl/youparle
Author: Franck Burlot
License-Expression: MIT AND BlueOak-1.0.0 AND OFL-1.1 AND Ubuntu-font-1.0
License-File: LICENSE
License-File: src/youparle/static/fonts/Fredoka-OFL.txt
License-File: src/youparle/static/fonts/Ubuntu-UFL.txt
License-File: src/youparle/vault_template/.obsidian/plugins/obsidian-spaced-repetition/LICENSE
License-File: src/youparle/vault_template/.obsidian/plugins/obsidian-spaced-repetition/THIRD-PARTY-NOTICES.txt
Keywords: language-learning,local-first,obsidian
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Education
Requires-Python: >=3.11
Requires-Dist: jinja2==3.1.6
Requires-Dist: numpy==2.4.6
Requires-Dist: pillow==12.3.0
Requires-Dist: platformdirs==4.11.10
Requires-Dist: soundfile==0.14.0
Description-Content-Type: text/markdown

# 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 the Microsoft voice, which sends the texts it speaks to Microsoft.

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](INSTALL.md). The agent
installs [uv](https://docs.astral.sh/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`, and asks them to restart the harness. No administrator
rights are needed.

By hand, from the course folder:

```bash
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:

```bash
youparle check
```

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

Installing youparle installs no voice. The agent offers one when it meets the
student, with the `voice` skill: the Microsoft voice, a program of the
student's own, or none. See [docs/voice.md](docs/voice.md).

## Commands

| Command | What it does |
|---|---|
| `youparle init [path]` | Make a vault from the template, or create what a vault is missing and rewrite the youparle block in `AGENTS.md`. Overwrites nothing else. |
| `youparle guide` | Print what to do at the start of a session, the skills, the tools, the rules that hold everywhere, and who the student is and how they want to be taught. |
| `youparle tmp clear` | Empty `agent/tmp/`, folders included. Run at the start of a session. |
| `youparle journal add <line>…` | Add lines at the end of today's journal, `agent/journal/YYYY-MM-DD.md`. A line about practice is checked: its competences, and its exercise. |
| `youparle skill <name>` | Print the steps for one task: `exercise`, `exercise-page`, `minimal-pairs`, `shadowing`, `lesson`, `card`, `feedback`, `onboarding`, `session-start`, `remember`, `update`, `voice`. |
| `youparle check` | Diagnose the installation: folder, memory files, Obsidian plugins, and the voice, which it tests by having it speak. |
| `youparle server start\|stop\|status` | Explicit control over the local server. The normal lifecycle is automatic. |
| `youparle exercise new <source.json>` | Validate an exercise and write it into `agent/exercises/`. |
| `youparle build-exercise <id>` | Render an exercise and open it in the browser. |
| `youparle lesson publish <draft.md> [--title …]` | Publish a draft into `lessons/`. |
| `youparle cards <proposal.json>` | Open the page where the student edits the proposed cards; each one validated is written into `cards/`. |
| `youparle fetch <url>… [--name …] [--header …]` | Download pictures, sounds, or files to read (JSON, JSON Lines, HTML, XML, text) into `agent/tmp/`, several at once. An address is typed as it reads, in any script. A header a source requires is sent with `--header`. |
| `youparle json <file>… [--path …]` | Print the outline of JSON or JSON Lines files in the vault, or what each path leads to in them. A path that finds nothing says what is there instead. |
| `youparle html <file>… [--select …] [--from …]` | Print the outline of HTML pages in the vault, or the text of what each selector matches in them, a table a row a line. `--from` reads the HTML that a JSON file holds. A selector that matches nothing says what is there instead. |
| `youparle tts --locale <locale> <text>… [--name …]` | Speak texts into mp3s in `agent/tmp/`, a voice drawn per text. |
| `youparle voice` | Show the voice of this machine. `voice use edge\|none\|custom` installs one or switches to one; `voice update` updates it. |
| `youparle open <path>` | Open a note of the vault in Obsidian. |

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/](docs/) explains why the package is built the way it is, and which rules
a change must not break. Start at [docs/README.md](docs/README.md).

## Developing

```bash
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](docs/vault.md) before changing it.

## Licence

MIT. See [LICENSE](LICENSE).

The vault template includes the Obsidian plugin
[Spaced Repetition](https://github.com/st3v3nmw/obsidian-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.
