Upload README.md with huggingface_hub

README.md

@@ -1,40 +1,26 @@
 ---
-language:
-- en
-- cy
-- ga
-- gd
+language: [en, cy, ga, gd]
 license: other
 library_name: transformers
-tags:
-- mother-core
-- agentic
-- tool-use
-- reasoning
-- rag
-- uk-sovereign
+tags: [mother-core, agentic, tool-use, reasoning, rag, code, uk-sovereign]
 pipeline_tag: text-generation
-base_model:
-- MediaStreamAI/MOTHER_CORE_V3
 ---
 
 # MOTHER CORE V3
 
-Sovereign UK reasoning + **agentic tool-calling** model by **MediaStream AI (MSAI)**.
-V3 fuses multi-step agent orchestration, retrieval-grounded answering, and UK-domain
-reasoning into a single ~6.9B model, served with `trust_remote_code`.
+Sovereign UK reasoning + **agentic** model by **MediaStream AI (MSAI)**. V3 is a
+~6.9B custom transformer trained on a 2.4M-record curriculum spanning reasoning,
+multi-step tool-calling, RAG, document/code generation, and safety — served via
+`trust_remote_code`.
 
 ## Eval (105-task agentic benchmark)
 
 | Version | Score | Degeneration |
 |---|---|---|
 | V2 (chunk 0600) | 51 / 105 (49%) | — |
-| **V3 (chunk 1550)** | **81 / 105 (77%)** | **2%** |
+| **V3 (chunk 1550)** | **81 / 105 (77%)** | low |
 
-+17 over V2; clean tool-call termination (degeneration 12% to 2%). Per-bucket:
-arithmetic 4/4, knowledge 5/5, identity 5/6, retrieval 9/11, comms/email 11/15,
-doc-generate 7/9, calendar 5/8, crm 6/12, format-export 8/20 (file-format routing
-is the known weak spot, being addressed in V3.1).
++30 tasks over V2; clean tool-call termination. Training ongoing toward 80%+.
 
 ## Architecture
 
@@ -42,86 +28,124 @@ Custom `MotherCoreModel` (requires `trust_remote_code=True`):
 
 | | |
 |---|---|
-| Parameters | ~6.9B (6.88B) |
-| Layers | 48 |
-| Hidden dim | 3072 |
-| Attention | 24 heads / 6 KV heads (GQA) |
-| FFN | 4x (SwiGLU) |
-| Max sequence | 4096 |
-| Positional | RoPE (theta 10000) |
-| Norm | RMSNorm (eps 1e-5) |
-| Vocab | 50258 (SentencePiece) |
-| Precision | bf16 |
-| Special tokens | BOS=1, EOS=2, PAD=0 |
-
-## Capabilities by agent group
-
-Trained on ~2.2M records across 8 capability groups (36 agent types).
-
-| Group | Area | Scope |
+| Parameters | ~6.9B |
+| Layers | 48 · hidden 3072 · 24/6 GQA · SwiGLU |
+| Context | 4096 · RoPE θ=10000 · RMSNorm |
+| Vocab | 50258 (SentencePiece) · bf16 |
+| Tokens | BOS=1 EOS=2 PAD=0 |
+
+---
+
+## Phase One — Training composition
+
+**2,400,092 records across 9 capability groups** (balanced-category sampling,
+per-category weights tuned for the agentic benchmark):
+
+| Group | Focus | Records |
 |---|---|---|
-| A | Arithmetic & math | calculator-tool use, step-by-step math CoT |
-| B | Reasoning & science | multi-domain step reasoning, science QA |
-| C | Knowledge & UK languages | UK knowledge, identity, Welsh / Irish / Scottish Gaelic |
-| D | Core agents & calc | general agent execution, calc tools, vertical agents |
-| E | RAG, chat & memory | retrieval (cite/synthesise/no-tool/fallback), multi-turn chat, memory |
-| F | Web, composition & recovery | web search, multi-tool composition, error recovery |
-| G | Orchestration & workflows | agent chains (2/3/5-step), CoT planning/replan, disambiguation, unsafe-refusal, workflows (invoice, onboarding, report, meeting) |
-| H | Documents, code, verify & plan | document & code generation, args-validation, verifier loops, DAG execution, planner/executor/policy agents |
+| A | Arithmetic & math CoT | 112,496 |
+| B | Reasoning & science | 439,463 |
+| C | Knowledge, identity & UK languages | 112,927 |
+| D | Core agents & calc | 327,400 |
+| E | RAG, chat & memory | 155,581 |
+| F | Web, composition & recovery | 73,284 |
+| G | Agent orchestration, CoT & workflows | 849,593 |
+| H | Documents, code, verification & planning | 303,348 |
+| I | Security & coding CoT | 26,000 |
+
+## Agents & abilities (Phase One)
+
+**A · Arithmetic & math** — `arithmetic` (79,978), `math_cot` (32,518): calculator-tool
+use, step-by-step numeric reasoning.
+
+**B · Reasoning & science** — `reasoning` (423,960), `science` (15,503): multi-domain
+chain-of-thought, scientific Q&A.
+
+**C · Knowledge, identity & UK languages** — `uk_knowledge` (22,874), `welsh` (30,462),
+`irish` (30,304), `scottish_gaelic` (15,258), `factual_general` (9,891),
+`identity` (4,138): UK domain knowledge, Welsh/Irish/Scottish-Gaelic, sovereign identity.
+
+**D · Core agents & calc** — `autm_agent` (275,000), `calc_tool` (32,400),
+`autm_vertical` (20,000): general agent execution + vertical-specialist agents
+(finance, compliance, insurance, regulatory, accounts, risk).
+
+**E · RAG, chat & memory** — retrieval (`rag_single_call`, `rag_synthesis`,
+`rag_with_citation`, `rag_not_needed`, `rag_empty_fallback`), conversation
+(`chat_multi_turn`, `chat_greeting`, `chat_identity`, `chat_acknowledgement`,
+`chat_helpful_refusal`, `chat_length_match`), memory (`memory_recall`,
+`memory_store`, `memory_multi_turn`, `memory_empty`): grounded answering with
+citation, multi-turn chat, long-term memory read/write.
+
+**F · Web, composition & recovery** — `web_search_single/reading/fallback`,
+`compose_rag_web/calc/multi/web_calc/calc_chain/memory_calc/web_memory`,
+`recovery_alternate/rewrite/admit_failure/malformed`, `tool_choice_routing`:
+web search, multi-tool composition, and graceful error recovery.
+
+**G · Orchestration, CoT & workflows** (largest group) — agent chains
+(`agent_chain_2step/3step/5plus`, `agent_conditional_chain`, `agent_cross_tier`),
+CoT (`agent_cot_planning/verification/synthesis/decomposition/replan`),
+robustness (`agent_disambiguation`, `agent_parallel_calls`, `agent_no_tool_needed`,
+`agent_args_hallucination_resist`, `agent_error_recovery`, `agent_mid_chain_abort`,
+`agent_oauth_required`, `agent_loop_aggregation`), **provider tool agents**
+(`agent_call_documents` 142,095, `agent_call_google` 49,310, `agent_call_composio`
+56,593, `agent_call_microsoft` 41,644), and end-to-end **workflows**
+(`workflow_proposal_pipeline`, `workflow_invoice_send`, `workflow_onboarding`,
+`workflow_report_generation`, `workflow_meeting_prep`, `workflow_msai_specific`),
+plus `agent_unsafe_refusal` (safety).
+
+**H · Documents, code, verification & planning** — `agent_call_code` (108,349),
+`agent_args_validation` (54,999), `agent_verifier_loop` (45,000),
+`agent_branch_merge`, `agent_dag_execution`, `agent_partial_failure_graph`,
+specialist agents (`planner_agent`, `executor_agent`, `verifier_agent`,
+`policy_agent`, `retrieval_agent`, `retrieval_arbiter`, `summarizer_agent`),
+and state control (`state_carryover`, `progressive_refinement`, `checkpoint_recall`,
+`contradiction_detection_and_repair`): document & code generation, argument
+validation, verifier loops, DAG/branch execution, multi-agent planning.
+
+**I · Security & coding CoT** — `security_cot` (12,000), `code_cot` (8,000),
+`code_rag` (6,000): security reasoning and retrieval-grounded code reasoning.
 
 ### Tool surface
 Calendar (`gcal_*`/`mscal_*`), email (`gmail_*`/`outlook_*`), CRM
-(`highlevel_*`/`mailchimp_*`/`activecampaign_*`/`kartra_*`), docs research
-(`gdrive_search`/`notion_search`/`gsheets_read`), tasks
-(`asana_*`/`todoist_*`/`gtasks_*`/`slack_post`), meetings
-(`fireflies_*`/`fathom_get_summary`), document generation
-(`doc_create_{pdf,word,excel,csv,json,html,markdown,pptx,...}`), code generation
-(`code_generate_{python,js,sql,shell}`), and finance/compliance/insurance/
-regulatory/accounts/risk verticals.
+(`highlevel_*`/`mailchimp_*`/`activecampaign_*`/`kartra_*`), docs/research
+(`gdrive_*`/`gdocs_*`/`gsheets_*`/`notion_*`), tasks (`asana_*`/`todoist_*`/
+`gtasks_*`/`slack_*`/`teams_*`), meetings (`fireflies_*`/`fathom_*`/`zoom_*`/
+`gmeet_*`), document generation (`doc_create_{pdf,word,excel,csv,json,html,
+markdown,pptx,…}`), code generation (`code_generate_{python,js,sql,shell}`), and
+finance/compliance/insurance/regulatory/accounts/risk verticals.
 
-## Inference
+---
 
-Loads with `trust_remote_code=True`. bf16, ~14 GB VRAM.
+## Inference
 
 ```python
 import torch
 from transformers import AutoModelForCausalLM, AutoTokenizer
-
-REPO = "MediaStreamAI/MOTHER_CORE_V3"
-tok = AutoTokenizer.from_pretrained(REPO, trust_remote_code=True)
-model = AutoModelForCausalLM.from_pretrained(
-    REPO, trust_remote_code=True, torch_dtype=torch.bfloat16, device_map="auto"
-).eval()
-
-def generate(message, max_new_tokens=256):
-    prompt = f"Question:\n\n{message}\n\nAnswer:"
-    ids = tok(prompt, return_tensors="pt").input_ids.to(model.device)
-    out = model.generate(ids, max_new_tokens=max_new_tokens, do_sample=False,
-                         repetition_penalty=1.2, no_repeat_ngram_size=4,
-                         pad_token_id=tok.pad_token_id)
+R = "MediaStreamAI/MOTHER_CORE_V3"
+tok = AutoTokenizer.from_pretrained(R, trust_remote_code=True)
+m = AutoModelForCausalLM.from_pretrained(R, trust_remote_code=True,
+                                         torch_dtype=torch.bfloat16, device_map="auto").eval()
+
+def ask(q, n=256):
+    ids = tok(f"Question:\n\n{q}\n\nAnswer:", return_tensors="pt").input_ids.to(m.device)
+    out = m.generate(ids, max_new_tokens=n, do_sample=False,
+                     repetition_penalty=1.2, no_repeat_ngram_size=4, pad_token_id=tok.pad_token_id)
     return tok.decode(out[0][ids.shape[1]:], skip_special_tokens=True).strip()
 
-print(generate("What is the capital of Scotland?"))   # -> Edinburgh is the capital of Scotland.
-Agentic tool-calling
-The model emits a single TOOL_CALL tool(args). Your runtime executes the tool
-and feeds the result back as a separate TOOL_RESULT {...} turn; the model then
-continues. It never fabricates the result — you supply it.
-
-USER: Build me an Excel file for capacity tracking
-ASSISTANT: TOOL_CALL doc_create_excel(title="capacity tracking", columns=["item","value"])
-TOOL: TOOL_RESULT {"success": true, "file": {"url": "...", "filename": "document.xlsx"}}
-ASSISTANT: Done - document.xlsx is ready. You can download it here: ...
-Loop: detect TOOL_CALL, run it, append TOOL_RESULT, call generate again with
-the transcript. Use greedy/deterministic decoding (sampling degrades tool-call
-validity); keep repetition_penalty=1.2, no_repeat_ngram_size=4.
-
-Limitations & safety
-format_export routing (Excel/CSV/etc.) still mis-routes ~half the time (V3.1).
-Knowledge is fixed at training time; verify facts.
-Non-weapon posture: observation + human-in-the-loop only. Refuses forgery,
-fraud, phishing and destructive actions; asks for confirmation on irreversible
-operations.
-Provenance
-MediaStream AI Limited — United Kingdom. Continued full fine-tune of the MOTHER
-CORE line on an NVIDIA GB10 (DGX Spark); answer-only loss, balanced category
-sampling, EOS-terminated targets, cosine LR warm-restart.
+print(ask("What is the capital of Scotland?"))   # Edinburgh is the capital of Scotland.
+```
+
+**Agentic loop:** the model emits a single `TOOL_CALL tool(args)`; your runtime runs
+it and feeds the result back as a separate `tool` turn (`TOOL_RESULT {...}`); the
+model then continues. Use greedy decoding; keep `repetition_penalty≈1.2`.
+
+## Limitations & safety
+- Some file-format routing still imperfect; arithmetic should be checked.
+- Non-weapon posture: observation + human-in-the-loop only; refuses forgery,
+  fraud, phishing, and destructive actions.
+- Knowledge fixed at training time — verify before acting.
+
+## Provenance
+MediaStream AI Limited (UK). Full fine-tune on an NVIDIA GB10 (DGX Spark);
+answer-only loss, balanced-category sampling, EOS-terminated targets, cosine-LR
+warm-restart. "Phase One" = the 2.4M-record agentic curriculum above.