Feat/tiny transformer impl

.agent/skills/general-visualization/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: general-visualization
+description: Format comparisons as aligned plain text with alternatives as columns, metrics as rows, decimal-point alignment, and inline winner-impact stars.
+---
+
+# General Visualization
+
+## Purpose
+
+Render quantitative results in a compact format that is easy to scan in terminal-style clients.
+Prefer aligned plain text blocks over Markdown tables unless the user explicitly asks for Markdown tables.
+
+## Core Rules
+
+- Use aligned plain-text rows for comparisons; do not use Markdown tables.
+- For comparisons, keep alternatives on the horizontal axis (columns) and metrics on the vertical axis (rows).
+- Use the real alternative names as column headers (for example, `fastText-ftz`, `transformer-int8`).
+- Do not use generic `Left`/`Right` headers or separate mapping notes.
+- Keep decimal points vertically aligned within each numeric column.
+- Keep one precision policy per output.
+- Default precision policy: 2 significant figures.
+- For decimals with absolute value under 1, omit the leading zero (`.84`, `-.07`).
+- Use a `change` column as absolute delta: `second alternative column - first alternative column`.
+- Format `change` as signed integer percentages (rounded) with percent signs aligned (`+3%`, `-6%`, `0%`).
+- Preserve units and directionality (`higher is better` vs `lower is better`).
+- Do not include a `better/worse` verdict column.
+- Do not use HTML tags for emphasis.
+- Attach the impact marker directly to the better value as a suffix.
+- Keep a fixed-width star slot so markers line up vertically (`*`, `**`, `***`, `****`).
+- For ties or near-ties (`<1%`), do not add any marker.
+- Impact markers:
+  - no marker for roughly equal (`0%` to `<1%`)
+  - `*` for `1%` to `<5%`
+  - `**` for `5%` to `<10%`
+  - `***` for `10%` to `50%`
+  - `****` for `>50%`
+- If direction is ambiguous, state the assumption explicitly.
+- Keep row labels short and stable (`Scam precision`, `Macro F1`, `Latency p95`).
+- Do not hide regressions.
+
+## Metric Direction Defaults
+
+- Higher is better: `precision`, `recall`, `f1`, `accuracy`, `auc`, `throughput`.
+- Lower is better: `fpr`, `fnr`, `latency`, `error`, `loss`, `size`, `memory`.
+- For unknown metric names, require an explicit assumption before choosing the better value.
+
+## Improvement Calculation
+
+- Compute signed change as `change% = (second alternative - first alternative) * 100`.
+- Determine which side is better using metric direction.
+- Use `abs(change%)` to choose marker strength.
+- If `abs(change%) < 1`, use no marker.
+
+## Workflow
+
+1. Collect rows: metric, baseline, candidate.
+2. Set direction for each metric.
+3. Determine the better value for each metric.
+4. Compute signed `change = second-column - first-column` in percentage points.
+5. Map `abs(change)` to impact marker (`*`, `**`, `***`, `****`) with no marker under `1%`.
+6. Append the marker to the winning value only and pad marker width for alignment.
+7. Render aligned rows with alternatives as columns and metrics as rows.
+
+## Output Templates
+
+### Side-by-Side Comparison (default, terminal-safe)
+
+Metric fastText-ftz transformer-int8 Change
+Scam precision .92 .95 \* +3%
+Scam recall .70 .78 _\*\* +8%
+Scam FPR .018 .012 -1%
+Macro F1 .83 .85 _ +2%
+
+### Comparison with Delta
+
+Metric baseline-v1 candidate-v2 Change
+Model size MB 3.4 3.1 ** -9%
+Scam recall .78 \* .76 -2%
+Latency p95 ms 58 ** 61 +5%
+
+## Style Controls
+
+- Keep output terminal-friendly plain text; avoid HTML tags entirely.
+- If user requests no table, still use aligned rows (not Markdown tables).
+- If output is short (1-3 metrics), keep to single compact block without extra sections.
+- Do not add a dedicated better/worse column unless explicitly requested.
+
+This skill intentionally uses no bundled scripts/resources.

.agent/skills/general-visualization/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "General Visualization"
+  short_description: "Present side-by-side metrics with aligned decimals and inline winner stars"
+  default_prompt: "Use this skill to format comparisons with alternatives as columns, metrics as rows, real alternative names as headers (no Left/Right), 2 sig figs, no leading zero for decimals under 1, decimal-point alignment, signed integer % change as second-column minus first-column, aligned percent signs, and fixed-width impact stars on the better value."

.agent/skills/huggingface/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: huggingface
+description: Sync Janitr experiment artifacts from remote to local and publish to Hugging Face experiments repo with single-index and manifest validation.
+---
+
+# Hugging Face Experiments Skill
+
+## Purpose
+
+Use the repo scripts to move experiment artifacts from the remote machine to a local clone of `janitr/experiments`, then commit and push.
+
+## Canonical Paths
+
+- Remote experiments clone: `/home/bob/offline/janitr-experiments`
+- Local experiments clone: `~/offline/janitr-experiments`
+- Remote-to-local sync script: `scripts/sync_experiments_from_remote.sh`
+- Remote artifact staging script: `scripts/sync_to_experiments_repo.py`
+- Dataset sync script: `scripts/sync_datasets_to_experiments_repo.py`
+- Index rebuild script: `scripts/rebuild_experiment_index.py`
+- Manifest validation script: `scripts/validate_experiment_runs.py`
+
+## Rules
+
+- Default sync is full repo sync. Do not pass `--run-id` unless explicitly requested.
+- Prefer the provided scripts over bare `rsync` commands.
+- Keep run naming format as `yyyy-mm-dd-<petname>` when creating new run directories.
+- Runs root must contain exactly one index file: `runs/INDEX.json`.
+- Always rebuild index after run changes and validate before commit/push.
+- Keep model artifacts at or below 30MB.
+- Use `--delete` when syncing remote to local to prevent stale/empty local run dirs.
+- Dataset snapshots use auto names `yyyy-mm-dd-<petname>` by default.
+- Dataset sync is deduplicated by content hash; no new snapshot is created when x-posts+x-replies files are unchanged.
+
+## Workflow
+
+1. Stage artifacts into the remote experiments clone:
+
+```bash
+python3 scripts/sync_to_experiments_repo.py \
+  --dest-root ~/offline/janitr-experiments \
+  --run-id 2026-02-15-flying-narwhal
+```
+
+2. Sync remote experiments repo to local (default full sync, no run filter, mirror mode):
+
+```bash
+bash scripts/sync_experiments_from_remote.sh \
+  --remote bob@<remote-host> \
+  --remote-path /home/bob/offline/janitr-experiments \
+  --dest ~/offline/janitr-experiments \
+  --delete
+```
+
+3. Optional dry-run before real sync:
+
+```bash
+bash scripts/sync_experiments_from_remote.sh \
+  --remote bob@<remote-host> \
+  --remote-path /home/bob/offline/janitr-experiments \
+  --dest ~/offline/janitr-experiments \
+  --delete \
+  --dry-run
+```
+
+4. Rebuild single index and validate manifests:
+
+```bash
+python3 scripts/rebuild_experiment_index.py \
+  --runs-root ~/offline/janitr-experiments/runs
+
+python3 scripts/validate_experiment_runs.py \
+  --runs-root ~/offline/janitr-experiments/runs \
+  --require-runs-root
+```
+
+5. Commit and push from local experiments clone:
+
+```bash
+cd ~/offline/janitr-experiments
+git status
+git add runs
+git commit -m "add experiment run(s)"
+git push
+```
+
+## Dataset Snapshots
+
+Use this to stage current x-posts + x-replies datasets into the experiments repo:
+
+```bash
+python3 scripts/sync_datasets_to_experiments_repo.py \
+  --dest-root ~/offline/janitr-experiments
+```
+
+Defaults:
+
+- x-posts dataset source: `data/sample.jsonl`
+- x-replies dataset source: `data/replies.jsonl`
+- snapshot id: auto-generated `yyyy-mm-dd-<petname>`
+
+Behavior:
+
+- Writes snapshot under `datasets/snapshots/<snapshot_id>/`.
+- Updates `datasets/INDEX.json`.
+- If content is unchanged (same hashes), does not create a duplicate snapshot.
+
+## Optional: Sync a Single Run
+
+Use only when explicitly asked:
+
+```bash
+bash scripts/sync_experiments_from_remote.sh \
+  --remote bob@<remote-host> \
+  --remote-path /home/bob/offline/janitr-experiments \
+  --dest ~/offline/janitr-experiments \
+  --run-id 2026-02-15-flying-narwhal
+```

.agent/skills/simpledoc/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: simpledoc
+description: Create or update documentation in this repo following SimpleDoc conventions. Use when creating docs, plans, logs, or any markdown files.
+---
+
+# SimpleDoc Documentation Skill
+
+**Attention agent!** Complete every item below before touching documentation work:
+
+1. **Read this file in full for the current session.** No shortcuts.
+2. **Verify that git is initialized and configured.** You will need the name and email of the current user in order to populate the `author` field in the YAML frontmatter. Run the following one-liner to verify:
+
+```bash
+printf '%s <%s>\n' "$(git config --local --get user.name 2>/dev/null || git config --global --get user.name)" "$(git config --local --get user.email 2>/dev/null || git config --global --get user.email)"
+```
+
+If the name and email are not available for some reason, ask the user to provide them, and also setup git configuration for them.
+
+## SimpleDoc Specification
+
+SimpleDoc defines two types of files:
+
+1. **Date-prefixed files**: SHOULD be used for most documents, e.g. `docs/2025-12-22-an-awesome-doc.md`.
+2. **Capitalized files**: SHOULD be used for general documents that are not tied to a specific time, e.g. `README.md`.
+
+### 1. Date-prefixed files
+
+- MUST put date-prefixed files in a top level `docs/` folder, or a subfolder `docs/<topic>/`. Subfolders MAY be nested indefinitely.
+- MUST use ISO 8601 date prefixes (`YYYY-MM-DD`) — the date MUST contain dashes.
+- After the date prefix, lowercase filenames SHOULD use dashes (`-`) as word delimiters (kebab-case). Avoid spaces and underscores.
+- The date prefix MAY be the entire filename (for example, daily logs like `docs/logs/2026-02-04.md`).
+- MUST NOT use capital letters in filename for Latin, Greek, Cyrillic and other writing systems that have lowercase/uppercase distinction.
+- MAY use non-ASCII characters.
+- Date-prefixed files SHOULD contain YAML frontmatter with at least `title`, `author` and `date` fields:
+  ```yaml
+  ---
+  title: Implementation Plan
+  author: John Doe <john.doe@example.com>
+  date: 2025-12-22
+  ---
+  ```
+- If present in YAML frontmatter, author SHOULD be of `Name <email>` per the RFC 5322 name-addr mailbox format and date SHOULD be ISO 8601 `YYYY-MM-DD` format.
+
+### 2. Capitalized files
+
+- For general documents not tied to a specific time, e.g. `README.md`, `AGENTS.md`, `INSTALL.md`, `HOW_TO_DEBUG.md`.
+- Multi-word filenames SHOULD use underscores (`CODE_OF_CONDUCT.md`).
+
+## Preferences in Documentation Style
+
+- Tone: casual, clear, technically precise but not academic
+- Planning docs: concrete and actionable, include checklists
+- Keep docs concise — no fluff, no filler paragraphs
+- Use ISO timestamps where relevant
+- Prefer bullet points over prose for technical content
+
+## Before You Start
+
+1. Run `date +%Y-%m-%d` and use the output for both filename prefix and `date` field.
+2. Identify where the document belongs:
+   - Keep general documentation at the root of `docs/`.
+   - Use dedicated subdirectories for specialized content (plans, logs, reports).
+3. Check for existing, related docs to avoid duplicates and to link to prior work.
+
+## File Naming
+
+- Format: `YYYY-MM-DD-descriptive-title.md`. The date MUST use dashes; the rest SHOULD be lowercase with hyphens (avoid underscores).
+- Choose names that reflect the problem or topic, not the team or author.
+- Example: `2025-06-20-api-migration-guide.md`.
+- Place the file in the appropriate folder before committing.
+
+### Timeless vs. Dated
+
+- **Timeless general documents** describe enduring processes or repo-wide rules. They do not carry a date prefix and keep their canonical names.
+- **All other content** (design notes, incidents, feature guides, migrations, meeting notes, plans, etc.) must use the date-prefixed naming pattern above.
+- When adding or reviewing documentation, decide which bucket applies.
+
+## Required Front Matter
+
+Every doc **must** start with YAML front matter:
+
+```yaml
+---
+date: 2025-10-24 # From `date +%Y-%m-%d`
+author: Name <email@example.com>
+title: Short Descriptive Title
+tags: [tag1, tag2] # Optional but recommended
+---
+```
+
+## Daily Logs (SimpleLog)
+
+Default location: `docs/logs/YYYY-MM-DD.md`.
+
+### Create a daily log entry
+
+```bash
+npx -y @simpledoc/simpledoc log "Entry text here"
+```
+
+For multiline:
+
+```bash
+cat <<'EOF' | npx -y @simpledoc/simpledoc log --stdin
+Multiline entry here
+- point one
+- point two
+EOF
+```
+
+### Manual edits (if needed)
+
+- Keep the YAML frontmatter intact (`title`, `author`, `date`, `tz`, `created`, optional `updated`).
+- Ensure a blank line separates entries.
+- Session sections must be `## HH:MM` (local time of the first entry in that section).
+
+### Ongoing logging
+
+Log anything worth noting: significant changes, decisions, errors, workarounds, progress. Log each entry after completing the step. No exceptions.
+
+## Final Checks Before Submitting
+
+- [ ] Filename follows the `YYYY-MM-DD-…` pattern and lives in the correct directory.
+- [ ] Front matter is complete and accurate.
+- [ ] Links to related documentation exist where applicable.
+- [ ] Run `npx -y @simpledoc/simpledoc check` to verify SimpleDoc conventions.

.github/workflows/ci.yml

@@ -18,17 +18,17 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Set up Python 3.12
-        uses: actions/setup-python@v5
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
         with:
-          python-version: "3.12"
+          version: "0.7.3"
 
       - name: Data integrity check
-        run: python scripts/check_integrity.py data/sample.jsonl
+        run: uv run --python 3.12 python scripts/check_integrity.py data/sample.jsonl
 
       - name: Duplicate ID dry-run check
         run: |
-          output="$(python scripts/fix_duplicate_ids.py data/sample.jsonl)"
+          output="$(uv run --python 3.12 python scripts/fix_duplicate_ids.py data/sample.jsonl)"
           echo "$output"
 
           duplicate_count="$(echo "$output" | awk -F': ' '/^Duplicate IDs:/ {print $2; exit}')"
@@ -56,16 +56,14 @@ jobs:
         with:
           node-version: "22"
 
-      - name: Set up Python 3.12
-        uses: actions/setup-python@v5
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
         with:
-          python-version: "3.12"
+          version: "0.7.3"
 
       - name: Install dependencies
         run: |
           npm install --no-audit
-          python -m pip install --upgrade pip
-          python -m pip install ruff
 
       - name: Prepare SimpleDoc CLI
         run: |