samvada 20261111.1__py3-none-any.whl

samvada/__init__.py

@@ -0,0 +1,6 @@
+"""Samvada: a voice and the habits of a language tutor for AI agents, offline first.
+
+The agent decides what to say; Samvada decides whether, where and how it is heard.
+"""
+
+__version__ = "20261111.1"

samvada/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+import sys
+sys.exit(main())

samvada/agents/__init__.py

@@ -0,0 +1 @@
+"""The agent layer: the rule, the skill, the hooks and `samvada setup` (DESIGN 7)."""

samvada/agents/hooks.py

@@ -0,0 +1,105 @@
+"""Hooks run by the agent harness (DESIGN 7.3): deterministic checks, no model call.
+
+`samvada hook prompt` (UserPromptSubmit): note the turn's start; when the voice is off, add one
+line of context so the agent does not compose speech nobody will hear.
+`samvada hook stop` (Stop): when the voice is on and `samvada speak` was not called since the
+turn started, ask the agent once to speak its closing.
+
+The harness sends the event as JSON on stdin (session_id, hook_event_name, stop_hook_active).
+A hook never breaks a session: any error is swallowed and the exit is 0.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+from ..state import State
+
+TURN, SPOKE, NUDGED = "turn", "spoke", "nudged"
+
+
+def _session_dir(state: State, session_id: str) -> Path | None:
+    if not session_id:
+        return state.session_dir
+    return state.root / "sessions" / f"claude-{session_id}"
+
+
+def _stamp(d: Path, name: str) -> None:
+    d.mkdir(parents=True, exist_ok=True)
+    (d / name).write_text(f"{time.time():.3f}\n")
+
+
+def _read(d: Path, name: str) -> float:
+    try:
+        return float((d / name).read_text().strip())
+    except (OSError, ValueError):
+        return 0.0
+
+
+def mark_spoke(state: State, env=os.environ) -> None:
+    """Called by `samvada speak`: the agent spoke this turn (whatever was heard).
+
+    Written under the session key and, inside Claude Code, under its session id too: the Stop
+    hook knows only the id, and the key may come from $SAMVADA_SESSION instead."""
+    dirs = {state.session_dir}
+    if env.get("CLAUDE_CODE_SESSION_ID"):
+        dirs.add(_session_dir(state, env["CLAUDE_CODE_SESSION_ID"]))
+    for d in dirs - {None}:
+        try:
+            _stamp(d, SPOKE)
+        except OSError:
+            pass
+
+
+def prompt(event: dict, state: State, decide) -> str | None:
+    d = _session_dir(state, event.get("session_id", ""))
+    if d is None:
+        return None
+    _stamp(d, TURN)
+    (d / NUDGED).unlink(missing_ok=True)
+    decision = decide(state)
+    if decision.on:
+        return None
+    return (f"Samvada: the voice is off now ({decision.why}). Keep the corrections and the "
+            "table; skip `samvada speak` this turn unless the owner asks for the voice.")
+
+
+def stop(event: dict, state: State, decide) -> str | None:
+    d = _session_dir(state, event.get("session_id", ""))
+    if d is None or event.get("stop_hook_active"):
+        return None
+    turn = _read(d, TURN)
+    if not turn or _read(d, SPOKE) >= turn or _read(d, NUDGED) >= turn:
+        return None  # no turn seen, already spoke, or already asked once this turn
+    if not decide(state).on:
+        return None
+    _stamp(d, NUDGED)
+    return ("Samvada: you did not call `samvada speak` this turn. Speak the closing now, one "
+            "call with every language (what was done, what is open, what needs the owner; "
+            "no symbols or paths), then stop.")
+
+
+def run(kind: str, state: State, decide) -> int:
+    try:
+        event = json.loads(sys.stdin.read() or "{}")
+    except (ValueError, OSError):
+        event = {}
+    try:
+        if kind == "prompt":
+            text = prompt(event, state, decide)
+            if text:
+                print(json.dumps({"hookSpecificOutput": {
+                    "hookEventName": event.get("hook_event_name", "UserPromptSubmit"),
+                    "additionalContext": text}}, ensure_ascii=False))
+        elif kind == "stop":
+            reason = stop(event, state, decide)
+            if reason:
+                print(json.dumps({"decision": "block", "reason": reason}, ensure_ascii=False))
+    except Exception as e:  # never break the session over a hook
+        print(f"samvada hook {kind}: {e}", file=sys.stderr)
+    return 0
+

samvada/agents/rule.md

@@ -0,0 +1,22 @@
+## Samvada: language tutor and voice
+
+The owner's native language is {native}; they are learning {learning}. For every message they
+send, before any other work:
+
+1. **Correct it.** Correct the grammar and wording of every language in the message and list
+   the corrections, with the IPA of a word whose sound or spelling was wrong. This is the
+   first text of the turn, printed before any tool call or work.
+2. **Show it in every language.** A table with one row per language: {rows}.{ipa}
+3. **Speak with `samvada speak`**, one call, every language passed in this order: the
+   message's own language first, then {order}.
+   - A question answered at once: one call at the end; each language says the corrected
+     question, then the answer.
+   - A task, or a question that needs real work: an **opening** call before the work ("you
+     are asking …; I will …"), and a **closing** call at the end with the conclusion: what
+     was done, what is still open, what needs the owner. Two to four sentences per language.
+   - Spoken text carries no symbols, code, paths or formulas.
+   - When `samvada` stays silent it says why and exits 0: never retry, never play sound
+     another way.
+
+Read the `samvada` skill for anything else: mute, scopes, languages, the online mode, a
+chat-bridge session, failures.

samvada/agents/setup.py

@@ -0,0 +1,239 @@
+"""`samvada setup`: give an agent the tutor's rule, the skill and the hooks (DESIGN 7.4).
+
+Prints the plan first (`--dry-run` stops there), then changes only what differs:
+  1. rule   the managed block between `samvada:begin` and `samvada:end` in CLAUDE.md
+            (Claude Code) or AGENTS.md (Codex), filled from the owner's settings
+  2. skill  skills/samvada/SKILL.md, copied (marked as Samvada's; a folder that is not ours
+            is never touched)
+  3. hooks  Claude Code only: UserPromptSubmit and Stop in settings.json; other hooks kept
+  4. voices whether each language of the rule has its voice pack (nothing is downloaded)
+
+Before a file is changed, a copy is kept beside it (<name>.samvada-backup-<time>).
+`--uninstall` removes exactly the block, the skill and the hooks it added.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import sys
+import time
+import tomllib
+from collections.abc import Mapping
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+
+from .. import engines, paths
+
+NAMES = {"en": "English", "zh": "Chinese", "ja": "Japanese", "fr": "French"}
+FLAGS = {"en": "🇺🇸 EN", "zh": "🇨🇳 ZH", "ja": "🇯🇵 JA", "fr": "🇫🇷 FR"}
+BEGIN = "<!-- samvada:begin (managed by `samvada setup`; change the settings, not this block) -->"
+END = "<!-- samvada:end -->"
+BLOCK_RE = re.compile(r"\n*<!-- samvada:begin.*?<!-- samvada:end -->\n?", re.S)
+MARKER = ".samvada-managed"
+HOOK_TAG = "-m samvada hook"
+
+
+@dataclass
+class Tutor:
+    native: str = "zh"
+    langs: tuple[str, ...] = ("en", "zh")
+    ipa: bool = True
+
+
+def config_path(env: Mapping[str, str] = os.environ) -> Path:
+    base = Path(env["XDG_CONFIG_HOME"]) if env.get("XDG_CONFIG_HOME") else Path.home() / ".config"
+    return base / "samvada" / "tutor.toml"
+
+
+def load_tutor(env: Mapping[str, str] = os.environ) -> Tutor:
+    try:
+        d = tomllib.loads(config_path(env).read_text())
+    except (OSError, ValueError):
+        return Tutor()
+    return Tutor(d.get("native", "zh"), tuple(d.get("langs", ("en", "zh"))), bool(d.get("ipa", True)))
+
+
+def save_tutor(t: Tutor, env: Mapping[str, str] = os.environ) -> None:
+    p = config_path(env)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    langs = ", ".join(f'"{l}"' for l in t.langs)
+    p.write_text(f'# Written by `samvada setup`; run it again after a change.\nnative = "{t.native}"\n'
+                 f"langs = [{langs}]\nipa = {'true' if t.ipa else 'false'}\n")
+
+
+def render_rule(t: Tutor) -> str:
+    learning = [NAMES[l] for l in t.langs if l != t.native] or [NAMES[l] for l in t.langs]
+    rows = []
+    for l in t.langs:
+        rows.append(FLAGS[l])
+        if l == "en" and t.ipa:
+            rows.append("🔤 IPA")
+    ipa = (" The IPA row transcribes the whole English row (General American): slashes, stress "
+           "marks, the flap ɾ, weak forms as spoken.") if t.ipa and "en" in t.langs else ""
+    body = resources.files("samvada").joinpath("agents", "rule.md").read_text().format(
+        native=NAMES[t.native], learning=", ".join(learning), rows=", ".join(rows), ipa=ipa,
+        order=", ".join(NAMES[l] for l in t.langs) + " (each language once)")
+    return f"{BEGIN}\n{body.rstrip()}\n{END}\n"
+
+
+def agent_dir(agent: str, env: Mapping[str, str] = os.environ) -> Path:
+    if agent == "claude":
+        return Path(env["CLAUDE_CONFIG_DIR"]) if env.get("CLAUDE_CONFIG_DIR") else Path.home() / ".claude"
+    return Path(env["CODEX_HOME"]) if env.get("CODEX_HOME") else Path.home() / ".codex"
+
+
+def _backup(p: Path) -> None:
+    if p.exists():
+        shutil.copy2(p, p.with_name(f"{p.name}.samvada-backup-{time.strftime('%Y%m%d-%H%M%S')}"))
+
+
+def _hook_command(kind: str) -> str:
+    return f'"{sys.executable}" {HOOK_TAG} {kind}'
+
+
+def _is_ours(entry: dict) -> bool:
+    return any(HOOK_TAG in h.get("command", "") for h in entry.get("hooks", []))
+
+
+def _indent(text: str) -> int:
+    m = re.search(r"\n( +)\S", text)
+    return len(m.group(1)) if m else 2
+
+
+class Step:
+    def __init__(self, name: str, desc: str, apply=None):
+        self.name, self.desc, self.apply = name, desc, apply
+
+
+def plan(agent: str, t: Tutor, uninstall: bool, env: Mapping[str, str] = os.environ) -> list[Step]:
+    home = agent_dir(agent, env)
+    steps: list[Step] = []
+
+    # 1. rule
+    rule_file = home / ("CLAUDE.md" if agent == "claude" else "AGENTS.md")
+    old = rule_file.read_text() if rule_file.exists() else ""
+    stripped = BLOCK_RE.sub("\n", old).rstrip("\n")
+    new = (stripped + "\n") if uninstall else ((stripped + "\n\n" if stripped else "") + render_rule(t))
+    if uninstall and new.strip() == stripped.strip() and BLOCK_RE.search(old) is None:
+        steps.append(Step("rule", f"no Samvada block in {rule_file}"))
+    elif new == old:
+        steps.append(Step("rule", f"unchanged in {rule_file}"))
+    else:
+        def write_rule(new=new):
+            rule_file.parent.mkdir(parents=True, exist_ok=True)
+            _backup(rule_file)
+            rule_file.write_text(new)
+        verb = "remove the block from" if uninstall else ("update the block in" if BLOCK_RE.search(old) else "add the block to")
+        steps.append(Step("rule", f"{verb} {rule_file}", write_rule))
+
+    # 2. skill
+    dest = home / "skills" / "samvada"
+    src = resources.files("samvada").joinpath("agents", "skills", "samvada", "SKILL.md").read_text()
+    ours = (dest / MARKER).exists()
+    if dest.exists() and not ours:
+        steps.append(Step("skill", f"{dest} exists and is not Samvada's: left alone"))
+    elif uninstall:
+        if ours:
+            steps.append(Step("skill", f"remove {dest}", lambda: shutil.rmtree(dest)))
+        else:
+            steps.append(Step("skill", f"not installed in {dest}"))
+    elif ours and (dest / "SKILL.md").exists() and (dest / "SKILL.md").read_text() == src:
+        steps.append(Step("skill", f"unchanged in {dest}"))
+    else:
+        def write_skill():
+            dest.mkdir(parents=True, exist_ok=True)
+            (dest / "SKILL.md").write_text(src)
+            (dest / MARKER).write_text("installed by `samvada setup`; `samvada setup --uninstall` removes it\n")
+        steps.append(Step("skill", f"{'update' if ours else 'install'} {dest / 'SKILL.md'}", write_skill))
+
+    # 3. hooks (Claude Code)
+    if agent == "claude":
+        sfile = home / "settings.json"
+        text = sfile.read_text() if sfile.exists() else "{}"
+        try:
+            settings = json.loads(text)
+        except ValueError:
+            steps.append(Step("hooks", f"{sfile} is not valid JSON: left alone"))
+            settings = None
+        if settings is not None:
+            hooks = settings.setdefault("hooks", {})
+            for event in ("UserPromptSubmit", "Stop"):
+                hooks[event] = [e for e in hooks.get(event, []) if not _is_ours(e)]
+                if not uninstall:
+                    kind = "prompt" if event == "UserPromptSubmit" else "stop"
+                    hooks[event].append({"hooks": [{"type": "command", "command": _hook_command(kind),
+                                                    "timeout": 10}]})
+                if not hooks[event]:
+                    del hooks[event]
+            if not hooks:
+                del settings["hooks"]
+            new_text = json.dumps(settings, indent=_indent(text), ensure_ascii=False) + "\n"
+            if json.loads(new_text) == json.loads(text):
+                steps.append(Step("hooks", f"unchanged in {sfile}"))
+            else:
+                def write_hooks(new_text=new_text):
+                    sfile.parent.mkdir(parents=True, exist_ok=True)
+                    _backup(sfile)
+                    sfile.write_text(new_text)
+                verb = "remove the UserPromptSubmit and Stop hooks from" if uninstall else \
+                    "set the UserPromptSubmit and Stop hooks in"
+                steps.append(Step("hooks", f"{verb} {sfile}", write_hooks))
+    else:
+        steps.append(Step("hooks", "Codex: no hooks; the rule and the skill carry the behaviour"))
+
+    # 4. voices (report only)
+    if not uninstall:
+        voices = engines.load_voices()
+        dirs = paths.voices_dirs(env)
+        missing = [l for l in t.langs if l in voices and not engines.has_pack(voices[l], dirs)]
+        steps.append(Step("voices", "every language has its voice pack" if not missing else
+                          f"no voice pack for {' '.join(missing)}: samvada voices add {' '.join(missing)}"))
+    return steps
+
+
+def main(args: list[str], env: Mapping[str, str] = os.environ) -> int:
+    agent, dry, uninstall = "claude", False, False
+    t = load_tutor(env)
+    it = iter(args)
+    for a in it:
+        if a == "--agent":
+            agent = next(it, "")
+        elif a == "--dry-run":
+            dry = True
+        elif a == "--uninstall":
+            uninstall = True
+        elif a == "--native":
+            t.native = next(it, "")
+        elif a == "--langs":
+            t.langs = tuple(l for l in next(it, "").split(",") if l)
+        elif a in ("--ipa", "--no-ipa"):
+            t.ipa = a == "--ipa"
+        else:
+            print(f"samvada setup: unknown argument {a}", file=sys.stderr)
+            return 2
+    if agent not in ("claude", "codex"):
+        print("samvada setup: --agent claude|codex", file=sys.stderr)
+        return 2
+    bad = [l for l in (*t.langs, t.native) if l not in NAMES]
+    if bad or not t.langs:
+        print(f"samvada setup: languages are {' '.join(NAMES)} (got {' '.join(bad) or 'none'})", file=sys.stderr)
+        return 2
+    steps = plan(agent, t, uninstall, env)
+    print(f"samvada setup ({agent}{', uninstall' if uninstall else ''}): native {t.native}, "
+          f"languages {','.join(t.langs)}, IPA {'on' if t.ipa else 'off'}")
+    for s in steps:
+        print(f"  {s.name:7} {s.desc}")
+    if dry:
+        print("dry run: nothing changed")
+        return 0
+    for s in steps:
+        if s.apply:
+            s.apply()
+    if not uninstall:
+        save_tutor(t, env)
+    print("done" + ("" if any(s.apply for s in steps) else ": nothing to change"))
+    return 0

samvada/agents/skills/samvada/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: samvada
+description: Speak to the owner with Samvada (the `samvada` command) and act as their language tutor - mute or unmute the voice (e.g. "we are watching TV", "unmute"), turn a language on or off for this session or everywhere, allow or forbid online voices, handle a silent or failed `samvada speak`, install or check voice packs, and the conventions of the correction table and its IPA row. Use whenever the owner talks about the voice, a language, muting, or when `samvada` prints something unexpected.
+---
+
+# Samvada: the voice and the tutor
+
+The always-on rule (in CLAUDE.md or AGENTS.md, between `samvada:begin` and `samvada:end`)
+says what to do on every message. This skill is the how-to for everything else.
+
+## Speaking
+
+```bash
+samvada speak en "<text>" zh "<text>" ja "<text>" fr "<text>"   # every language, in order
+```
+
+- **One call per opening or closing**, every language passed. Samvada skips the languages that
+  are off or have no voice installed; you never need to know the settings.
+- **Spoken text is plain language**: strip code, paths, formulas, symbols, URLs.
+- **Silent is fine.** `samvada` decides where the voice plays (the owner at this desk, screen
+  unlocked, not muted, not on the phone). When silent it prints the reason on stderr and
+  exits 0: do not retry, do not fall back to another player.
+- **Exit 1** means a language failed with every engine allowed; say so in one line and go on.
+  `SAMVADA_DEBUG=1` shows the engine's own output. **Exit 2** is a usage error: fix the call.
+
+## The owner's words → the command
+
+| The owner says | Run |
+|---|---|
+| "we are watching TV", "watching with my son", "陪孩子看电视", "mute" | `samvada mute "watching TV"` (once), and say once that the voice is muted |
+| "unmute", "TV is over", "speak again" | `samvada unmute` |
+| "mute this session", "quiet here" | `samvada --session mute "<why>"` |
+| "no Japanese anymore", "turn off French everywhere" | `samvada lang off ja` (global) |
+| "turn off French here", "only English in this session" | `samvada --session lang off fr` |
+| "bring French back here" | `samvada --session lang on fr`; `samvada --session lang reset` drops this session's choices |
+| "online mode", "use edge tts" | `samvada online always`; "safe mode", "offline mode" → `samvada online off` |
+| "allow online when a voice fails" | `samvada online fallback` |
+
+Unclear whether they mean this session or everywhere: choose the session, and say so. A mute
+in either scope silences; for languages and the online mode, the session wins over global.
+While muted, keep the corrections and the table; only the voice stops. Do not play any other
+sound (no test audio, no clients started with sound).
+
+`samvada status` says where the voice goes now and why, which languages are on, the online
+mode, and the session key (the Claude Code session id, kept across a resume; else the pys
+window; else the tty; or `$SAMVADA_SESSION`).
+
+## Online voices
+
+Off by default: the owner's words never leave the machine. `fallback` retries only a language
+that failed offline with edge-tts; `always` sends every language online. Both need the online
+extra (`pip install 'samvada[online]'`); `samvada online <mode>` says when it is missing.
+`SAMVADA_ONLINE=off|fallback|always` overrides for one call.
+
+## Voice packs
+
+```bash
+samvada voices                 # installed where, size, engine
+samvada voices add ja fr       # download (pinned, checksummed), install, and the engine if missing
+samvada voices verify          # check the installed files against voices.lock
+```
+
+A language without a pack is skipped (offline) with "no voice pack". Suggest `samvada voices
+add <lang>` once; do not install on your own: it downloads tens to hundreds of MB.
+
+## The table and its IPA row
+
+- One row per language the rule lists, natural phrasing in each, not word-for-word.
+- The IPA row (when the rule asks for it) transcribes the whole English row, General American:
+  slashes around it, stress marks (ˈ) on words of two or more syllables, the flap ɾ where
+  Americans say it (little → ˈlɪɾəl), weak forms as spoken in a sentence (to → tə, and → ənd).
+- In a correction about one word's sound or spelling, give that word's IPA too.
+
+## Sessions that are not at a desk
+
+- **Chat bridge** (the reply is shown in a chat on a phone; the system prompt says so):
+  do not speak (the bridge runs with `SAMVADA=off`, so a call would be silent anyway). Keep
+  the corrections and the table; if the chat cannot render a table, give one line per
+  language: `EN: …`, `ZH: …`.
+- **Headless runs** set `SAMVADA=off`. A chat bridge that hears from the owner on the phone
+  runs `samvada presence phone`, so the desk stays silent until the owner types there again.
+
+## Hooks (installed by `samvada setup`)
+
+- Before a turn, a hook notes the turn's start, and adds one line of context when the voice
+  is off ("the voice is off: …"), so you do not compose speech nobody will hear.
+- At the end of a turn, if the voice is on and `samvada speak` was not called since the turn
+  started, a hook asks you once to speak the closing. Speak it, then stop.