{"id":51509125,"url":"https://github.com/mikhailvs/loqui","last_synced_at":"2026-07-08T04:01:31.810Z","repository":{"id":367202699,"uuid":"1279468482","full_name":"mikhailvs/loqui","owner":"mikhailvs","description":"An evidence-based agent harness for teaching a spoken language — pedagogy in code, push-to-talk voice loop, local LLM.","archived":false,"fork":false,"pushed_at":"2026-06-25T02:17:39.000Z","size":165,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-25T03:06:49.615Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mikhailvs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-24T18:03:54.000Z","updated_at":"2026-06-25T02:17:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mikhailvs/loqui","commit_stats":null,"previous_names":["mikhailvs/loqui"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mikhailvs/loqui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikhailvs%2Floqui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikhailvs%2Floqui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikhailvs%2Floqui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikhailvs%2Floqui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mikhailvs","download_url":"https://codeload.github.com/mikhailvs/loqui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikhailvs%2Floqui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35251017,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-08T02:00:06.796Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-08T04:01:30.813Z","updated_at":"2026-07-08T04:01:31.802Z","avatar_url":"https://github.com/mikhailvs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# loqui\n\n\u003e *loqui* — Latin, \"to speak.\"\n\nAn **agent harness for teaching a spoken language**, where the pedagogy lives in\nthe harness — *not* in the model's prompt. The LLM only realizes moves; the\nharness owns scheduling, learner state, and a set of **falsifiable invariants**\nthat veto any move violating good pedagogy. The invariant set *is* the auditable\ncurriculum.\n\nIt runs as a **push-to-talk voice tutor**: you speak, it transcribes you, the\nharness decides what to teach next, an LLM writes the line, and it speaks back —\nin a few seconds, fully local.\n\nThe whole design is grounded in an evidence sweep of second-language-acquisition,\ncognitive-science-of-learning, and intelligent-tutoring-systems research, with\nevery claim adversarially fact-checked (effect sizes, replication status,\nengagement-vs-learning confounds). See **[DESIGN.md](DESIGN.md)** and the\n**[EVIDENCE.md](EVIDENCE.md)** appendix.\n\n## How it works\n\n```\n you speak ─▶ Whisper (STT) ─▶ HARNESS ─▶ LLM realizes ─▶ edge-tts ─▶ it speaks\n                                  │          the move          back\n              drives + invariants ┘   (claude -p or local Ollama)\n```\n\n- **The harness decides** every turn: which of five drives (Repair / Review /\n  Progress / Engage / Consolidate) wins, and which concrete move it becomes —\n  then **vetoes** any move that breaks an invariant (e.g. \"never quiz an\n  un-taught word\", \"never mass an item\", \"grade only delayed production\").\n- **The LLM only writes** the chosen move's text and grades free speech. Swap the\n  brain freely: a `claude -p` CLI fallback, or a local/LAN Ollama model.\n- **Languages are data.** A target language is just a curriculum file plus\n  STT/TTS/brain language settings — switch between *learning* one (Portuguese)\n  and *QA-ing the system* in one you speak natively (Russian).\n\n## Run\n\n```bash\npip install --user faster-whisper edge-tts          # STT + TTS\n# a brain: either the `claude` CLI on PATH, or an Ollama endpoint:\nexport BRAIN_URL=http://localhost:11434/api/chat BRAIN_MODEL=qwen3:8b\n\n# voice tutor (HTTPS, self-signed — needed for mic access in the browser)\nopenssl req -x509 -newkey rsa:2048 -keyout .key.pem -out .cert.pem -days 365 \\\n  -nodes -subj \"/CN=localhost\" -addext \"subjectAltName=DNS:localhost,IP:127.0.0.1\"\npython voiceserver.py            # open https://localhost:8443\n\n# or, no audio/LLM needed — watch the harness drive a simulated learner:\npython run_session.py            # text trace of drives + invariant vetoes\npython tests/test_harness.py     # prove the invariants fire\n```\n\n## Layout\n\n| path | role |\n|---|---|\n| `harness/model.py` | learner model — declarative-vs-production states, retrievability |\n| `harness/scheduler.py` | forgetting curve + spaced scheduling |\n| `harness/drives.py` | the five drives: score + propose candidate moves |\n| `harness/invariants.py` | the veto layer (the auditable pedagogy) |\n| `harness/arbiter.py` | per-turn loop: propose → veto → select → ingest |\n| `harness/curricula/{pt,ru}.json` + `curricula.py` | frequency-ordered curricula (data) + loader |\n| `harness/languages.py` | language profiles (curriculum + STT/TTS/brain language) |\n| `brain.py` | LLM seam (Ollama / `claude -p`), structured-output JSON |\n| `voice.py` / `voiceserver.py` | edge-tts + the push-to-talk web app |\n| `tutor.py` / `run_session.py` | CLI tutor / simulated-learner runner |\n\n## Status\n\nResearch prototype. The harness, learner model, and a representative subset of the\ninvariants are implemented and tested; the voice loop works end-to-end (~2–3s/turn\non a warm local model). It is **not** validated as *effective* — that needs real\nlearners and delayed post-tests; the design's instrumentation is built to collect\nexactly that. See `DESIGN.md §5` for the open empirical questions.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikhailvs%2Floqui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikhailvs%2Floqui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikhailvs%2Floqui/lists"}