Create README.md

README.md

@@ -0,0 +1,103 @@
+---
+license: other
+language: [en, fr]
+tags: [agent, tool-use, structured-output, autonomous, edge, offline, sparsemind]
+base_model: AMFORGE/samg-cobratooling
+pipeline_tag: text-generation
+---
+
+# SAM-G-Agent
+
+**SAM-G-Agent** is the autonomous-agent member of the SAM-G family: a ~30M-parameter,
+offline, dual-mode model that acts as the **per-step tool dispatcher** of a long-running
+agentic loop (Manus / Claude-Code style). Given an instruction or the current state of a
+task, it emits the **next action(s)** as a compact, risk-flagged JSON plan that an
+executor runs against real tools.
+
+It is **not** a monolithic long-horizon planner. An agent built on SAM-G-Agent runs for
+hours by a host **loop** that re-invokes the model each turn with the latest observation;
+the model returns one short action at a time. This design plays to the model's strength
+(short, reactive tool emission) and around its limit (long exactly-ordered chains).
+
+## What it does
+
+Input: a natural-language instruction (EN/FR), optionally followed by an observation
+block (` intent | {observation}`). Output, after the `[ACTION]` mode token:
+
+```json
+{"plan":[{"op":"web_search","args":{"query":"latest diffusion models"},"risk":"safe"}]}
+```
+
+A terminal `{"op":"finish","args":{...}}` tells the host loop to stop.
+
+### Tool vocabulary
+
+| op | purpose | default risk |
+|---|---|---|
+| `web_search` | query the web | safe |
+| `scrape_page` | fetch a page's content | safe |
+| `read_arxiv` | read an arXiv paper | safe |
+| `browse` | navigate a site (open / click / scroll / extract); submit/download gated | safe / critical |
+| `execute_python` | run Python; gated when it touches os/subprocess/files/network | safe / critical |
+| `generate_image` | text-to-image | safe |
+| `ffmpeg` | video/audio editing (trim, concat, overlay, subtitles, extract audio) | safe |
+| `download_file` | fetch a file to disk | **critical** |
+| `transfer_token` | move crypto / value | **always critical** |
+| `summarize` / `ask_llm` | condense / delegate hard reasoning to a larger model | safe |
+| `finish` | terminate the agent loop | safe |
+| inherited dev ops | `open_file`, `list_dir`, `run_command`, `write_file`, `git_push`, `api_call`, `db_query` | per op |
+
+### Behaviour families (training coverage)
+
+- **dispatch** — instruction → one tool call (the strongest mode).
+- **search_react / code_react / browse_react** — react to an observation (results,
+  stdout/error, page state) with the next action: refine, fix-and-retry, extract, finish.
+- **research_chain** — `web_search → scrape_page → summarize`.
+- **media_pipeline** — `download_file → ffmpeg → finish` (gated).
+- **risk_gate_agent** — plans mixing safe + critical ops (transfer / download / system code).
+- **autonomous_step** — `goal + state → the single next op` (incl. `finish`): the loop primitive.
+- **dev_dispatch** — replay of inherited IDE/dev ops (anti-forgetting).
+
+## Safety: risk flag + mandatory deterministic backstop
+
+Every op carries a learned `risk` flag (`safe` / `critical`) meant to drive a
+user-confirmation gate. **The flag is advisory, not the safety boundary.** The host
+application MUST enforce a deterministic policy that forces confirmation on
+known-dangerous operations regardless of the flag — in particular:
+
+- `transfer_token` (value movement) — **always** confirm; never auto-execute;
+- `download_file`, external `api_call` mutations, and `execute_python` that touches
+  the filesystem / network / system — confirm;
+- `run_command` matching dangerous patterns (e.g. `rm -rf`, `git push`), `git_push`,
+  `write_file`, `open_app` — confirm.
+
+The flag may only *harden* (safe → critical), never permit. Treat a missing critical
+flag as a false negative to be caught by the backstop.
+
+## Intended use
+
+The structured-action stage of an autonomous agent: research assistants, media-editing
+pipelines (ffmpeg), browser/YouTube navigation, code-execution loops, on-device
+automation. Runs fully offline; the executor supplies the actual tools.
+
+## Limitations (honest)
+
+- **Short chains, looped — not long monolithic plans.** Reactive 1–3-op emission is
+  the model's strength; tasks needing one long exactly-ordered plan must be
+  **decomposed by the host loop into short steps**. This is by design, not a regression.
+- ~30M scale: limited open-ended reasoning and world knowledge; delegate hard reasoning
+  via `ask_llm` to a larger model.
+- French covers agentic instructions, not free prose.
+- Tool set is fixed at fine-tune time; new tools require additional fine-tuning.
+- Benchmarks are synthetic (disjoint seed); they validate routing/format/risk-gating,
+  not real-world tool success, which depends on the executor.
+
+## Lineage
+
+`SAM-G (base, dual-mode)` → `SAM-G-Reasoning` → `SAM-G-CobraTooling (IDE tools, robust)`
+→ **`SAM-G-Agent` (autonomous tool dispatcher)**.
+
+## Disclosure
+
+Architecture internals, tokenizer construction, data generators, and ablations are
+proprietary and withheld. This card documents the released artifact only.