lingo-loop 0.1.0__py3-none-any.whl

language_tutor/__init__.py

@@ -0,0 +1,3 @@
+"""Local-first language tutor core."""
+
+__version__ = "0.1.0"

language_tutor/_assets/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "language-tutor",
+  "version": "0.1.0",
+  "description": "Local-first language tutor for Claude Code",
+  "author": {
+    "name": "language-tutor contributors"
+  },
+  "license": "MIT"
+}

language_tutor/_assets/.codex-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "schema_version": "1.0",
+  "name": "language-tutor",
+  "version": "0.1.0",
+  "description": "Local-first language tutor packaged as a Codex plugin (reuses root skills/).",
+  "author": "language-tutor contributors",
+  "license": "MIT",
+  "skills": "./skills/",
+  "features": {
+    "plugin_hooks": false
+  }
+}

language_tutor/_assets/hermes-profile/SOUL.md

@@ -0,0 +1,30 @@
+# Language Tutor (Hermes Profile Prompt)
+
+You are a patient, source-backed language tutor running inside the Hermes
+host. You operate text-only: reading, lessons, transcripts, vocabulary,
+writing, and progress reporting. You do not produce or consume audio or
+images.
+
+## Lifecycle
+
+Hermes does not provide SessionStart/SessionEnd hooks for this profile.
+Boot context is built on demand via an explicit tutor command (the
+operator runs the tutor's boot command after `hermes profile install`).
+There is no automatic session-end hook; end-of-session work is invoked
+explicitly when requested.
+
+## Boot context
+
+When the explicit tutor boot command runs, load the learner profile and
+preferences through the tutor core and render the boot context sections.
+Never invent learner state; rely on the core's persisted data, which lives
+outside this distribution.
+
+## Behavior contract
+
+- Keep all interaction text-only and terminal-readable.
+- Defer pedagogy, feedback, progress, and persistence to the tutor core.
+- Never echo, package, or export learner secrets, memories, sessions,
+  database state, logs, or local overrides.
+- Stay within the declared capability profile: no audio, no images, no
+  host-specific side effects beyond the documented text flows.

language_tutor/_assets/hermes-profile/config.yaml

@@ -0,0 +1,37 @@
+# Hermes profile configuration defaults for the language-tutor agent.
+# Defaults only. No learner data, no secrets, no machine-local state.
+schema_version: 1
+
+# Capability declaration mirrors src/language_tutor/adapters/registry.py
+# (HostId.HERMES). Source of truth stays in the registry; this is a
+# documentation echo for operators inspecting the distribution.
+capabilities:
+  text_support: supported
+  audio_support: unsupported
+  image_support: unsupported
+  lifecycle_start: explicit_command
+  lifecycle_end: not_available
+  boot_context_trigger: explicit_tutor_command
+
+# Tutor flows exposed by this profile. All text-only.
+flows:
+  - reading
+  - lesson
+  - transcript
+  - vocab
+  - writing
+  - progress
+
+# Hermes profile lifecycle commands (documentation for operators).
+commands:
+  install: hermes profile install
+  update: hermes profile update
+  inspect: hermes profile info language-tutor
+  list: hermes profile list
+  remove: hermes profile delete language-tutor
+
+# Operator-supplied environment is read from the operator's own untracked
+# .env at runtime. This distribution ships no values.
+env:
+  source: operator_local_env
+  bundled_values: false

language_tutor/_assets/hermes-profile/distribution.yaml

@@ -0,0 +1,49 @@
+# Hermes profile distribution manifest for the language-tutor agent.
+# Distribution metadata and defaults only. Contains NO learner-owned data.
+# Installed/updated via `hermes profile install` / `hermes profile update`.
+schema_version: 1
+name: language-tutor
+display_name: Language Tutor
+version: 0.1.0
+description: >-
+  Source-backed language-learning tutor profile for Hermes. Provides
+  text-only reading, lesson, transcript, vocab, writing, and progress
+  flows backed by the host-independent tutor core. No audio or image
+  capabilities.
+license: MIT
+source_url: https://github.com/artemVeduta/lingo-loop
+
+# Whole-agent package contents (git-backed distribution).
+profile:
+  prompt: SOUL.md
+  config: config.yaml
+  # Tutor skills are reused from the repository root `skills/` surface; this
+  # distribution does not ship its own skills/ tree.
+  skills: ../skills
+
+# Environment variables the operator must supply locally before launch.
+# Declared here for documentation only; values are never bundled. The actual
+# secrets live in the operator's own untracked .env (NOT shipped).
+env_requires:
+  - name: ANTHROPIC_API_KEY
+    required: true
+    description: API key for the tutor model provider. Operator-supplied; never bundled.
+
+# Hard exclusions: data that must never be packaged, copied, or published.
+exclude:
+  - ".env"
+  - "*.env"
+  - secrets
+  - memories
+  - sessions
+  - "*.sqlite"
+  - "*.sqlite3"
+  - "*.db"
+  - "*.db-wal"
+  - "*.db-shm"
+  - logs
+  - "*.log"
+  - caches
+  - "*.cache"
+  - local
+  - local_overrides

language_tutor/_assets/openclaw-plugin/openclaw.plugin.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://docs.openclaw.ai/plugins/manifest.schema.json",
+  "id": "language-tutor",
+  "name": "Language Tutor",
+  "displayName": "Language Tutor",
+  "version": "0.1.0",
+  "description": "Text-only language tutor adapter for OpenClaw. Builds boot context on the first tutor message and exposes core text-modality tutor tools.",
+  "entry": "dist/index.js",
+  "activation": {
+    "onStartup": true
+  },
+  "contracts": {
+     "tools": ["language_tutor"]
+   },
+  "configSchema": {
+    "type": "object",
+    "properties": {},
+    "additionalProperties": false
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "capabilities": {
+    "text": "supported",
+    "audio": "unsupported",
+    "image": "unsupported"
+  },
+  "lifecycle": {
+    "start": "first_message",
+    "end": "not_available",
+    "bootContextTrigger": "first_tutor_message"
+  },
+  "tools": [
+    {
+      "name": "language_tutor.boot_context",
+      "optional": false
+    },
+    {
+      "name": "language_tutor.text_exercise",
+      "optional": false
+    },
+    {
+      "name": "language_tutor.run_cli",
+      "optional": true
+    }
+  ]
+}

language_tutor/_assets/openclaw-plugin/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@language-tutor/openclaw-plugin",
+  "version": "0.1.0",
+  "description": "OpenClaw host plugin for the language-tutor text-modality adapter.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "openclaw": {
+    "extensions": ["./dist/index.js"]
+  },
+  "files": [
+    "dist",
+    "src",
+    "openclaw.plugin.json"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc --noEmit -p tsconfig.json"
+  },
+  "peerDependencies": {
+    "openclaw": ">=1.0.0"
+  },
+  "dependencies": {
+    "typebox": "^1.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  }
+}

language_tutor/_assets/openclaw-plugin/src/index.ts

@@ -0,0 +1,68 @@
+// Language Tutor plugin entry for the OpenClaw host.
+//
+// Uses focused SDK subpath imports (NOT a whole-SDK wildcard import) per the
+// OpenClaw plugin model: https://docs.openclaw.ai/plugins
+//
+// Capability stance (mirrors src/language_tutor/adapters/registry.py OpenClaw
+// defaults): text supported; lifecycle start = first_message; lifecycle end =
+// not_available; boot context is built on the first tutor message. Any
+// side-effectful / binary-dependent tool is registered opt-in only.
+
+import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";
+import { Type } from "typebox";
+
+export default defineToolPlugin({
+  id: "language-tutor",
+  name: "Language Tutor",
+  description:
+    "Text-only language tutor adapter for OpenClaw. Builds boot context on the first tutor message and exposes core text-modality tutor tools.",
+  tools: (tool) => [
+    // First-message boot trigger: OpenClaw has no SessionStart-style hook, so
+    // the tutor assembles boot context the first time the learner messages
+    // the tutor.
+    tool({
+      name: "language_tutor.boot_context",
+      description:
+        "Assemble learner boot context (profile, preferences, focus) on the first tutor message.",
+      parameters: Type.Object({
+        sessionId: Type.Optional(Type.String()),
+      }),
+      async execute(_params, _config, _context) {
+        // Pure text assembly only. No persistence or host-specific behavior
+        // here; the core tutor owns boot-context generation.
+        return { sections: [] as string[] };
+      },
+    }),
+    // Text-modality tutor tool (reading / lesson / transcript / vocab /
+    // writing / progress are all text-only flows). No side effects beyond
+    // returning text.
+    tool({
+      name: "language_tutor.text_exercise",
+      description:
+        "Present and evaluate a text-only tutor exercise (reading, lesson, transcript, vocab, writing, progress).",
+      parameters: Type.Object({
+        modality: Type.String(),
+        payload: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+      }),
+      async execute(params, _config, _context) {
+        return { modality: params.modality, text: "" };
+      },
+    }),
+    // Side-effectful / binary-dependent tool. Shells out to the local tutor
+    // CLI, so it is OPT-IN ONLY and gated behind a user allowlist.
+    tool({
+      name: "language_tutor.run_cli",
+      description:
+        "Invoke the local language-tutor CLI. Binary-dependent and side-effectful; opt-in only.",
+      optional: true,
+      parameters: Type.Object({
+        command: Type.Array(Type.String()),
+      }),
+      async execute(params, _config, _context) {
+        // Execution is performed by the host only after the user allowlists
+        // it.
+        return { command: params.command };
+      },
+    }),
+  ],
+});

language_tutor/_assets/openclaw-plugin/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src"]
+}

language_tutor/adapters/__init__.py

@@ -0,0 +1 @@
+"""Host adapter boundaries."""

language_tutor/adapters/base.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from language_tutor.schemas import (
+    APPROVED_HOST_SOURCES,
+    AdapterCapabilityProfile,
+    BootContextTrigger,
+    ConformanceRun,
+    HostId,
+    HostSetupProfileContract,
+    HostSetupTarget,
+    ManualProviderInstallReport,
+    SetupModel,
+    SetupPackage,
+    TargetStatus,
+)
+
+
+class JsonCommandRunner(Protocol):
+    def run_json(
+        self, args: list[str], payload: dict[str, object] | None = None
+    ) -> dict[str, object]:
+        """Run a host-facing JSON command."""
+        ...
+
+
+class HookPayloadAdapter(Protocol):
+    def normalize(self, payload: dict[str, object]) -> dict[str, object]:
+        """Normalize host hook payload into core JSON."""
+        ...
+
+
+class HostCapabilityProvider(Protocol):
+    def capability_profile(self) -> AdapterCapabilityProfile:
+        """Return the host's declared capability profile."""
+        ...
+
+
+class LifecycleTriggerProvider(Protocol):
+    def boot_trigger(self) -> BootContextTrigger:
+        """Return the host's boot-context lifecycle trigger."""
+        ...
+
+
+class SetupPackageProvider(Protocol):
+    def setup_package(self) -> SetupPackage:
+        """Describe the host-owned distribution package."""
+        ...
+
+
+class ConformanceRunner(Protocol):
+    def run_conformance(self) -> ConformanceRun:
+        """Run shared host-portability conformance checks."""
+        ...
+
+
+class ManualReportProvider(Protocol):
+    def manual_report(self) -> ManualProviderInstallReport:
+        """Return the host's manual provider install report."""
+        ...
+
+
+# Supported host target registry (US1). Single source of truth for the four
+# approved hosts, their official setup-doc sources, setup models, and contract
+# paths. Antigravity is intentionally absent and rejected at the schema layer.
+_REGISTRY: dict[HostId, HostSetupTarget] = {
+    HostId.HERMES: HostSetupTarget(
+        id=HostId.HERMES,
+        display_name="Hermes",
+        official_source_url=APPROVED_HOST_SOURCES[HostId.HERMES.value],
+        setup_model=SetupModel.PROFILE_DISTRIBUTION,
+        primary_subagent="hermes-adapter-subagent",
+        contract_path="specs/006-agent-adapter-setup/contracts/host-setup-profiles/hermes.md",
+        status=TargetStatus.PLANNED,
+    ),
+    HostId.OPENCLAW: HostSetupTarget(
+        id=HostId.OPENCLAW,
+        display_name="OpenClaw",
+        official_source_url=APPROVED_HOST_SOURCES[HostId.OPENCLAW.value],
+        setup_model=SetupModel.PLUGIN_PACKAGE,
+        primary_subagent="openclaw-adapter-subagent",
+        contract_path="specs/006-agent-adapter-setup/contracts/host-setup-profiles/openclaw.md",
+        status=TargetStatus.PLANNED,
+    ),
+    HostId.CLAUDE: HostSetupTarget(
+        id=HostId.CLAUDE,
+        display_name="Claude",
+        official_source_url=APPROVED_HOST_SOURCES[HostId.CLAUDE.value],
+        setup_model=SetupModel.PLUGIN_PACKAGE,
+        primary_subagent="claude-adapter-subagent",
+        contract_path="specs/006-agent-adapter-setup/contracts/host-setup-profiles/claude.md",
+        status=TargetStatus.PLANNED,
+    ),
+    HostId.CODEX: HostSetupTarget(
+        id=HostId.CODEX,
+        display_name="Codex",
+        official_source_url=APPROVED_HOST_SOURCES[HostId.CODEX.value],
+        setup_model=SetupModel.LOCAL_MARKETPLACE_PLUGIN,
+        primary_subagent="codex-adapter-subagent",
+        contract_path="specs/006-agent-adapter-setup/contracts/host-setup-profiles/codex.md",
+        status=TargetStatus.PLANNED,
+    ),
+}
+
+
+def supported_host_targets() -> dict[HostId, HostSetupTarget]:
+    """Return the registry of approved host setup targets."""
+    return dict(_REGISTRY)
+
+
+def is_supported_host(host_id: str) -> bool:
+    """True only for hermes, openclaw, claude, codex. Antigravity is rejected."""
+    return host_id in {h.value for h in HostId}
+
+
+def get_host_target(host_id: str) -> HostSetupTarget:
+    return _REGISTRY[HostId(host_id)]
+
+
+def normalize_hook_payload(payload: dict[str, object]) -> dict[str, object]:
+    return dict(payload)
+
+
+def run_conformance(profile: AdapterCapabilityProfile) -> ConformanceRun:
+    """Build a deterministic conformance result from a host capability profile.
+
+    The runner is host-blind: it derives the six representative-flow outcomes
+    from the declared capability profile (a gated flow is ``skipped``, every
+    other flow ``pass``) and reports the shared boot/feedback/progress/error/
+    data-ownership contract results. It owns no pedagogy or learner state.
+    """
+    from language_tutor.schemas import (
+        ConformanceRun,
+        Decision,
+        FlowResult,
+        RepresentativeFlow,
+    )
+
+    gated = {str(g) for g in profile.flow_gates}
+    flows: dict[RepresentativeFlow, FlowResult] = {}
+    for flow in RepresentativeFlow:
+        flows[flow] = FlowResult.SKIPPED if flow.value in gated else FlowResult.PASS
+
+    skipped = [f for f in RepresentativeFlow if f.value in gated]
+    has_fail = any(r == FlowResult.FAIL for r in flows.values())
+    decision = Decision.FAIL if has_fail else Decision.PASS
+
+    return ConformanceRun(
+        host=HostId(str(profile.host)),
+        capability_profile="schemas/host_capability_profile.schema.json",
+        flows=flows,
+        boot_context_result=FlowResult.PASS,
+        feedback_contract_result=FlowResult.PASS,
+        progress_contract_result=FlowResult.PASS,
+        error_behavior_result=FlowResult.PASS,
+        data_ownership_result=FlowResult.PASS,
+        skipped_flows=skipped,
+        decision=decision,
+    )
+
+
+def load_host_setup_profile(path: str) -> HostSetupProfileContract:
+    """Load and validate a host setup profile markdown contract.
+
+    The markdown contract embeds a fenced ```json block describing the
+    HostSetupProfileContract fields. This loader extracts and validates it.
+    """
+    import json
+    import re
+    from pathlib import Path
+
+    text = Path(path).read_text(encoding="utf-8")
+    match = re.search(r"```json\s*(\{.*?\})\s*```", text, re.DOTALL)
+    if not match:
+        raise ValueError(f"host setup profile {path} has no json contract block")
+    data = json.loads(match.group(1))
+    return HostSetupProfileContract.model_validate(data)

language_tutor/adapters/claude.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from language_tutor.adapters.registry import capability_profile_for
+from language_tutor.schemas import AdapterCapabilityProfile, HostId
+
+
+def capability_profile() -> AdapterCapabilityProfile:
+    """Claude capability profile. No-hook lifecycle (spec 007)."""
+    return capability_profile_for(HostId.CLAUDE.value)
+
+
+def plugin_root_components() -> dict[str, str]:
+    return {
+        "manifest": ".claude-plugin/plugin.json",
+        "setup_skill": "skills/tutor-setup/SKILL.md",
+        "vocab_skill": "skills/tutor-vocab/SKILL.md",
+        "writing_skill": "skills/tutor-writing/SKILL.md",
+        "progress_skill": "skills/tutor-progress/SKILL.md",
+        "judge_agent": "agents/tutor-judge.md",
+        "cli": "bin/tutor",
+    }

language_tutor/adapters/codex.py

@@ -0,0 +1,16 @@
+"""Codex host adapter.
+
+Codex distributes as a local-marketplace plugin and boots the tutor on the
+first tutor-skill invocation (no plugin hook required). Setup is package-only.
+This module exposes the host capability profile and leaves pedagogy, feedback,
+progress, and learner state to the tutor core.
+"""
+
+from __future__ import annotations
+
+from language_tutor.adapters.registry import capability_profile_for
+from language_tutor.schemas import AdapterCapabilityProfile, HostId
+
+
+def capability_profile() -> AdapterCapabilityProfile:
+    return capability_profile_for(HostId.CODEX.value)

language_tutor/adapters/hermes.py

@@ -0,0 +1,16 @@
+"""Hermes host adapter.
+
+Hermes uses a git-backed profile distribution and has no Claude-style startup
+hook, so it boots the tutor through an explicit command trigger. Setup is
+package-only; this module exposes the host capability profile and leaves all
+pedagogy, feedback, progress, and learner state to the tutor core.
+"""
+
+from __future__ import annotations
+
+from language_tutor.adapters.registry import capability_profile_for
+from language_tutor.schemas import AdapterCapabilityProfile, HostId
+
+
+def capability_profile() -> AdapterCapabilityProfile:
+    return capability_profile_for(HostId.HERMES.value)

language_tutor/adapters/openclaw.py

@@ -0,0 +1,16 @@
+"""OpenClaw host adapter.
+
+OpenClaw distributes as a Node/TypeScript ESM plugin package and has no
+Claude-style startup hook, so it boots the tutor on the first tutor message.
+Setup is package-only; this module exposes the host capability profile and
+leaves pedagogy, feedback, progress, and learner state to the tutor core.
+"""
+
+from __future__ import annotations
+
+from language_tutor.adapters.registry import capability_profile_for
+from language_tutor.schemas import AdapterCapabilityProfile, HostId
+
+
+def capability_profile() -> AdapterCapabilityProfile:
+    return capability_profile_for(HostId.OPENCLAW.value)

language_tutor/adapters/registry.py

@@ -0,0 +1,81 @@
+"""Host capability profile defaults (single source of truth).
+
+Each supported host declares its capability profile here. Host-specific adapter
+modules (claude.py, codex.py, hermes.py, openclaw.py) may translate runtime
+behavior, but capability declarations stay centralized to keep flow names,
+lifecycle values, and boot triggers DRY.
+"""
+
+from __future__ import annotations
+
+from language_tutor.schemas import (
+    AdapterCapabilityProfile,
+    BootTrigger,
+    CapabilitySupport,
+    HostId,
+    LifecycleEnd,
+    LifecycleStart,
+)
+
+_DEFAULTS: dict[HostId, AdapterCapabilityProfile] = {
+    HostId.CLAUDE: AdapterCapabilityProfile(
+        host=HostId.CLAUDE,
+        display_name="Claude",
+        text_support=CapabilitySupport.SUPPORTED,
+        lifecycle_start=LifecycleStart.FIRST_MESSAGE,
+        lifecycle_end=LifecycleEnd.NOT_AVAILABLE,
+        boot_context_trigger=BootTrigger.FIRST_TUTOR_MESSAGE,
+        setup_entry_point="claude --plugin-dir <plugin-root>",
+        update_behavior="/reload-plugins",
+        side_effectful_capabilities=[],
+        unsupported_capabilities=["audio", "image"],
+        flow_gates=[],
+    ),
+    HostId.CODEX: AdapterCapabilityProfile(
+        host=HostId.CODEX,
+        display_name="Codex",
+        text_support=CapabilitySupport.SUPPORTED,
+        lifecycle_start=LifecycleStart.FIRST_MESSAGE,
+        lifecycle_end=LifecycleEnd.NOT_AVAILABLE,
+        boot_context_trigger=BootTrigger.FIRST_TUTOR_MESSAGE,
+        setup_entry_point="local marketplace install via .codex-plugin/plugin.json",
+        update_behavior="Codex restart/reload after marketplace update",
+        side_effectful_capabilities=[],
+        unsupported_capabilities=["audio", "image"],
+        flow_gates=[],
+    ),
+    HostId.HERMES: AdapterCapabilityProfile(
+        host=HostId.HERMES,
+        display_name="Hermes",
+        text_support=CapabilitySupport.SUPPORTED,
+        lifecycle_start=LifecycleStart.FIRST_MESSAGE,
+        lifecycle_end=LifecycleEnd.NOT_AVAILABLE,
+        boot_context_trigger=BootTrigger.FIRST_TUTOR_MESSAGE,
+        setup_entry_point="hermes profile install",
+        update_behavior="hermes profile update",
+        side_effectful_capabilities=[],
+        unsupported_capabilities=["audio", "image"],
+        flow_gates=[],
+    ),
+    HostId.OPENCLAW: AdapterCapabilityProfile(
+        host=HostId.OPENCLAW,
+        display_name="OpenClaw",
+        text_support=CapabilitySupport.SUPPORTED,
+        lifecycle_start=LifecycleStart.FIRST_MESSAGE,
+        lifecycle_end=LifecycleEnd.NOT_AVAILABLE,
+        boot_context_trigger=BootTrigger.FIRST_TUTOR_MESSAGE,
+        setup_entry_point="openclaw plugins install <package-name>",
+        update_behavior="reinstall/upgrade plugin package",
+        side_effectful_capabilities=["binary-dependent tools (opt-in via user allowlist)"],
+        unsupported_capabilities=["audio", "image"],
+        flow_gates=[],
+    ),
+}
+
+
+def default_capability_profiles() -> dict[HostId, AdapterCapabilityProfile]:
+    return dict(_DEFAULTS)
+
+
+def capability_profile_for(host_id: str) -> AdapterCapabilityProfile:
+    return _DEFAULTS[HostId(host_id)]