Create README.md

README.md

@@ -0,0 +1,163 @@
+---
+license: apache-2.0
+language:
+- en
+- fr
+library_name: transformers
+pipeline_tag: text-generation
+tags:
+- agentic
+- function-calling
+- tool-use
+- structured-generation
+- orchestration
+- code-agent
+- mcp
+- edge
+- small-language-model
+base_model: AMFORGE/samg-reasoning
+model-index:
+- name: SAM-G-CobraTooling
+  results:
+  - task:
+      type: agentic-orchestration
+      name: Agentic IDE tool-call orchestration (13 families, held-out)
+    metrics:
+    - type: exact_match
+      value: 78.8
+      name: Exact plan match, aggregate (%)
+    - type: accuracy
+      value: 94.0
+      name: Risk-gate fidelity (%)
+---
+
+# SAM-G-CobraTooling
+
+**SAM-G-CobraTooling** is a 30.3M-parameter model fine-tuned from
+[SAM-G-Reasoning](https://huggingface.co/AMFORGE/samg-reasoning) on 196k
+agentic orchestration traces. It turns a natural-language instruction — or an
+observation from a previous step — into an **ordered, risk-flagged JSON plan of
+tool calls**. It is the local orchestration layer of an agentic IDE: it routes,
+decomposes, tracks state, reacts to exit codes and HTTP status, and emits
+structured tool calls entirely offline. It does **not** write code; code is
+delegated to a larger model via an `ask_code_model` hand-off. Built by
+**AMEFORGE** for the CobraBub IDE.
+
+- **Parameters:** 30.3M · **Footprint:** 121 MB fp32 (~30 MB quantized) · **Base:** SAM-G-Reasoning
+- **Fine-tuning:** prompt-masked SFT (loss on the plan span only), cosine 8e-5, 10k steps, best at 6k
+- **Aggregate exact plan-match:** 78.8% (held-out, disjoint seed)
+- **Lineage:** SAM-G → SAM-G-Reasoning → SAM-G-CobraTooling
+
+## Output format
+
+```
+<instruction>                     [ACTION] {"plan":[{"op":...,"args":{...},"risk":"safe|critical"}, ...]}
+<intent> | {"last_op":...,"...":...} [ACTION] {"plan":[ ... ]}      # reactive (observation-driven)
+```
+
+Every step carries a `risk` flag (`safe` or `critical`) that drives the IDE
+confirmation gate: safe ops run autonomously, critical ops require explicit
+user confirmation.
+
+## What it is good at — and what it is not
+
+Stress-tested on thirteen families. The pattern mirrors the rest of the SAM-G
+line: it excels at **routing and reaction** (short, procedural) and is limited
+on **long ordered chains** that must match exactly at 30M parameters.
+
+| Family | Exact % | Type |
+|---|---|---|
+| single_tool (routing) | 100 | routing |
+| retry_loop (exit-code state machine) | 100 | reaction |
+| feedback_react (stdout/stderr) | 100 | reaction |
+| git_workflow (status→add→push, gated) | 100 | procedural |
+| scrape_research (fetch→summarize→act) | 100 | procedural |
+| db_query (SQL, SELECT vs mutation) | 100 | structured call |
+| webhook_wait (async callback) | 92 | async reaction |
+| **mcp_call (filesystem/github/postgres)** | **83** | **structured call** |
+| api_call (REST/GraphQL + HTTP state machine) | 75 | structured call |
+| plan_chain (multi-step plans) | 58 | planning |
+| risk_gate (mixed safe/critical plans) | 58 | gated planning |
+| fs_watch (file-change reaction) | 42 | async reaction |
+| build_test_cycle (edit→test→react + hand-off) | 17 | long chain |
+
+Routing, exit-code reaction, git, scraping and SQL routing are saturated.
+`mcp_call` at 83% makes the model a viable local driver for MCP servers — the
+core capability of a hosted code agent, here running offline. `plan_chain` rose
+from the v1 plateau (0–42%) to 58% after broadening generator coverage.
+`build_test_cycle` remains the hard family: four-to-five ordered ops ending in a
+code-model hand-off, scored by strict exact match — the same long-chain ceiling
+seen with arithmetic in SAM-G-Reasoning. For those, decompose app-side into
+shorter sub-calls.
+
+## Security: the risk flag is advisory, not a boundary
+
+The model flags critical ops with **94% fidelity** across all families — strong
+for pre-flagging and good UX. **It must not be the sole security boundary.** A
+30M model will mis-flag a fraction of decisions, and the failure modes are
+asymmetric: a false negative (a critical op flagged `safe`) would auto-run a
+destructive command without confirmation. Integrators must add a
+**deterministic backstop**: a hard whitelist/blacklist in the app that forces
+`critical` on known-dangerous operations (`rm -rf`, `git push`, `DROP`/`DELETE`,
+external mutating HTTP, MCP write tools, `delete_file`) regardless of the
+model's flag. Treat the model's `risk` field as a fast hint that pre-fills the
+confirmation gate, with the app's deterministic rules as the enforced boundary.
+
+## Op vocabulary
+
+Routing/IO: `open_file`, `list_dir`, `run_command`, `scrape`, `summarize`,
+`capture`, `open_app`. Hand-off: `ask_code_model`, `write_file`. Control:
+`retry`, `escalate`, `backoff`, `reauth`, `continue`, `stop`. Integrations:
+`api_call`, `mcp_call`, `db_query`, `webhook_wait`, `fs_watch`, `git_push`.
+
+## Intended use
+
+The local planning/routing/reaction layer of an agentic IDE: decompose an
+instruction into ordered tool calls, react to observations (exit codes, stderr,
+HTTP status, DB row counts, webhook payloads, file-change events), and emit
+structured, risk-flagged plans offline and for free. Roughly the procedural
+majority of agentic turns; hard code generation and long exact chains are
+escalated to a larger model via `ask_code_model`.
+
+## Usage
+
+```python
+import sentencepiece as spm, torch
+sp = spm.SentencePieceProcessor(); sp.Load("samg_tokenizer.model")
+
+# routing
+prompt = "open src/main.js and run the tests [ACTION]"
+# -> {"plan":[{"op":"open_file","args":{"path":"src/main.js"},"risk":"safe"},
+#             {"op":"run_command","args":{"cmd":"pytest"},"risk":"safe"}]}
+
+# reactive: HTTP 429 -> back off and retry
+prompt = "rate limited, back off and retry | {\"last_op\":\"api_call\",\"status\":429} [ACTION]"
+# -> {"plan":[{"op":"backoff","args":{"seconds":30},"risk":"safe"},
+#             {"op":"retry","args":{"attempt":2},"risk":"safe"}]}
+
+ids = torch.tensor([sp.EncodeAsIds(prompt)])
+# greedy-decode the [ACTION] span -> structured plan JSON
+```
+
+## Limitations
+
+- `build_test_cycle` (17%) and the exact-match of `plan_chain`/`risk_gate`
+  (58%) plateau because long, strictly-ordered plans are hard at 30M; decompose
+  long plans app-side into shorter sub-calls.
+- The `risk` flag is advisory (94% fidelity); enforce a deterministic backstop
+  in the app, as above.
+- Traces are synthetic, drawn from the training family distribution with a
+  disjoint evaluation seed; coverage reflects the generator, not arbitrary
+  real-world tool APIs.
+- Not a general assistant and does not write code; it orchestrates and hands
+  off. Inherits the base model's knowledge limits.
+
+## Citation
+
+```bibtex
+@misc{samgcobratooling2026,
+  title  = {SAM-G-CobraTooling: Risk-Flagged Agentic Tool-Call Orchestration at 30M Parameters},
+  author = {AMEFORGE Lab},
+  year   = {2026}
+}
+```