magma-core 2.0.0__py3-none-any.whl

magma_core/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: BSD-2-Clause
+# Copyright (c) 2026, Loan Bernat
+
+__version__ = "2.0.0"

magma_core/_clients/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: BSD-2-Clause
+# Copyright (c) 2026, Loan Bernat
+
+from .client_base import LLMClientBase
+from .client_factory import ClientFactory
+
+__all__ = ["LLMClientBase", "ClientFactory"]

magma_core/_clients/client_base.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: BSD-2-Clause
+# Copyright (c) 2026, Loan Bernat
+
+from abc import ABC, abstractmethod
+from typing import List, Dict, Any, Optional
+
+from magma_core.configs import BackendConfig
+
+class LLMClientBase(ABC):
+    """
+    Base class to create a custom LLM CLient to handle payload sended by the workers for coaching, user simulation, curriculum etc...
+    """
+
+    def __init__(self, config: BackendConfig):
+        self.config = config
+
+    @abstractmethod
+    def send_prompt(
+        self,
+        model: Optional[str],
+        prompt: str,
+        max_tokens: int
+    ) -> str:
+        ...
+
+    @abstractmethod
+    def send_messages(
+        self,
+        model: Optional[str],
+        messages: List[Dict[str, Any]],
+        max_tokens: int,
+        keep_messages: bool = False
+    ) -> Any:
+        ...
+
+    def test_server(self):
+        self.send_prompt(
+            self.config.default_model,
+            "Hello how are you?",
+            max_tokens=50
+        )

magma_core/_clients/client_factory.py

@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: BSD-2-Clause
+# Copyright (c) 2026, Loan Bernat
+
+from typing import Type
+from .client_base import LLMClientBase
+from .ollama_client import OllamaClient
+
+from magma_core.configs.config import BackendConfig
+
+CLIENT_REGISTRY: dict[str, Type[LLMClientBase]] = {
+    "ollama" : OllamaClient
+}
+
+class ClientFactory:
+
+    @staticmethod
+    def create_client(backend_config : BackendConfig):
+        if backend_config.type not in CLIENT_REGISTRY:
+            raise ValueError(f"Unknown LM Backend {backend_config.type}. Avalaible are : {','.join(CLIENT_REGISTRY.keys())}")
+
+        ClientCLS = CLIENT_REGISTRY[backend_config.type]
+        return ClientCLS(backend_config)

magma_core/_clients/ollama_client.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: BSD-2-Clause
+# Copyright (c) 2026, Loan Bernat
+
+import requests
+import json
+
+from .client_base import LLMClientBase
+
+class OllamaClient(LLMClientBase):
+    """
+    Client for a Ollama Server
+    """
+    
+    def _send(self, data, url, keep_messages=False):
+        for _ in range(self.config.max_retry):
+            try:
+                r = requests.post(
+                    url,
+                    headers=self.config.headers,
+                    data=json.dumps(data),
+                    timeout=self.config.timeout
+                )
+                msg = r.json()["choices"][0]["message"]
+                return msg if keep_messages else msg["content"]
+            except Exception as e:
+                print("Error when posting request to Ollama: " + str(e))
+                continue
+        raise RuntimeError("Ollama unreachable")
+
+    def send_prompt(self, model, prompt, max_tokens):
+        data = {
+            "model": model if model is not None else self.config.default_model,
+            "messages": [{"role": "user", "content": prompt}],
+            "max_tokens": max_tokens
+        }
+        return self._send(data, self.config.endpoint)
+
+    def send_messages(self, model, messages, max_tokens, keep_messages=False):
+        data = {
+            "model": model if model is not None else self.config.default_model,
+            "messages": messages,
+            "max_tokens": max_tokens
+        }
+        return self._send(
+            data,
+            self.config.endpoint,
+            keep_messages
+        )

magma_core/_prompts/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: BSD-2-Clause
+# Copyright (c) 2026, Loan Bernat

magma_core/_prompts/coach/diagnostic/coach_diagnose.py

@@ -0,0 +1,120 @@
+COACH_DIAGNOSIS="""
+You are a privileged trajectory coach.  
+  
+You analyze a FAILED execution after the episode has finished.  
+  
+Your task is to identify the EARLIEST decision responsible for preventing the completion of the current Stage Goal.  
+  
+You are NOT asked to repair the trajectory.  
+  
+--------------------------------------------------  
+CORE PRINCIPLE  
+--------------------------------------------------  
+
+Identify the EARLIEST SEMANTIC DECISION ERROR in the trajectory.
+
+A semantic decision error is the earliest action that deviates from a valid
+progress-making strategy for the Stage Goal, given the privileged task state
+and constraints.
+
+IMPORTANT:
+- Execution success does NOT imply that a decision was correct.
+- A successful action can still be the root error if it selects the wrong
+  object, wrong robot, wrong ordering, or violates a prerequisite required
+  by a later operation.
+- Do NOT select the first bad_call merely because it is where the problem
+  became observable.
+- A later invalid action may be only a consequence of an earlier incorrect
+  commitment.
+
+A decision should be selected if its effect must later be undone, corrected,
+or recovered from before a valid completion of the Stage Goal can continue.
+
+COUNTERFACTUAL TEST:
+For candidate decision k:
+1. Keep all decisions BEFORE k unchanged.
+2. Replace decision k with a correct alternative.
+3. Decisions AFTER k are NOT fixed: they may be replanned and re-executed
+   from the corrected resulting state.
+4. If this restores a valid progress-making continuation, k is a valid
+   candidate.
+5. Among valid candidates, select the earliest one.
+  
+--------------------------------------------------  
+EXECUTION FAILURES  
+--------------------------------------------------  
+  
+Execution failures and decision errors are different.  A correct decision may fail because of stochastic execution.  
+  
+Never select a decision ONLY because its execution failed. Instead, evaluate whether the subsequent recovery decisions remained consistent with achieving the Stage Goal. 
+
+If decision X failed due to a 'Stochastic Failure' it will be flagged with 'injection error', that's means that this step can not be the error excepts if the action is not giving any progress toward the goals. Most of the time, the faulty step will be the very next decision because it does not retry.
+
+--------------------------------------------------  
+SPECIFIC FAILURE INFORMATION  
+--------------------------------------------------  
+  
+{specific_failure_paragraph}
+
+--------------------------------------------------
+TASK-SPECIFIC COACHING GUIDANCE
+--------------------------------------------------
+
+{task_coaching_hint}
+
+{validated_similar_cases}
+
+--------------------------------------------------  
+TASK  
+--------------------------------------------------  
+  
+{stage_goal}
+  
+--------------------------------------------------  
+TRAJECTORY  
+--------------------------------------------------  
+  
+Decisions with index 0 belong to the validated trajectory prefix. They MUST be considered correct and CANNOT be selected.  
+
+{trajectory}
+END OF TRAJECTORY  
+  
+--------------------------------------------------  
+OUTPUT  
+--------------------------------------------------  
+  
+Return exactly one JSON object and nothing else.
+Do not use Markdown.
+Do not wrap the JSON in a code fence.
+The first output character must be {{ and the last output character must be }}.
+The decision_index must be a strictly positive integer corresponding to a
+selectable decision in the trajectory. Never return 0 or a negative index.
+  
+{{  
+"decision_index": <integer>,  
+"reason": "<why this is the earliest causal decision>",  
+"expected_decision": "<what should have happened instead>"  
+}}
+"""
+
+FAILURE_PARAGRAPHE = {
+    "failure" : """
+The trajectory terminated after an invalid or repetitive action.
+
+This termination signal indicates WHERE the failure became visible, not
+necessarily WHERE the policy first made an incorrect decision.
+
+Trace backward to the earliest semantic decision error that placed the
+trajectory on this incorrect branch.
+""",
+    "no_action": """
+The execution terminated before completing the current Stage Goal because the final action do not contains any tools.
+That implies that the model drift during the trajectory.
+If the model encountered multiple stochastic error, be sure to have try all possible options (objects,zone) that can be used.
+""",
+    "exceeded": """
+The episode exceeded the maximum number of decisions before completing the Stage Goal.
+Look for ineffective recovery behaviour, unnecessary repetitions, or missed opportunities that prevented completion.
+Do not simply select the last repeated decision unless it is the first decision that made completion impossible.
+"""
+}

magma_core/_prompts/coach/diagnostic/diag_non_optimal.py

@@ -0,0 +1,119 @@
+# SPDX-License-Identifier: BSD-2-Clause
+# Copyright (c) 2026, Loan Bernat
+
+DIAGNOSIS_SUB_OPTI = """\
+You are a privileged trajectory coach analyzing a SUCCESSFUL agent trajectory.
+
+The trajectory completed the Stage Goal but required more steps than the expected target.
+This does NOT necessarily mean that it is suboptimal: additional steps may be justified by stochastic execution, partial observations, ambiguous feedback, or necessary recovery.
+
+Your task is to determine whether there is a clear local opportunity to complete the SAME Stage Goal with fewer decisions.
+
+If yes, identify the EARLIEST decision that should be modified.
+
+--------------------------------------------------
+CORE RULE
+--------------------------------------------------
+
+A decision at index k is a valid candidate if, while keeping ALL previous
+decisions fixed, replacing that decision could plausibly:
+
+1. still complete the Stage Goal;
+2. avoid one or more later decisions;
+3. reduce the total number of decisions.
+
+Select the EARLIEST such decision.
+
+Do NOT propose the replacement action.
+
+--------------------------------------------------
+CAUSALITY AND INFORMATION
+--------------------------------------------------
+
+Each step contains:
+
+INPUT:
+information available before the decision.
+
+TOOL:
+decision made by the agent.
+
+RESULT:
+Flag of the error types
+
+Judge whether a decision was reasonable using only information available
+in its INPUT and previous trajectory.
+
+You may use later steps to understand the consequences of an earlier
+decision, but do NOT use information that was unavailable to the agent
+to claim that an earlier decision was suboptimal.
+
+EXECUTION STOCHASTICITY
+
+A correct decision may lead to additional steps because execution failed
+or feedback was uncertain. IN this case it will be marked by injection_error.
+
+Do NOT mark as suboptimal:
+- justified retries after stochastic failures;
+- observations needed to resolve uncertain or incomplete feedback;
+- necessary exploration;
+- appropriate recovery after execution failure;
+- correct partial progress.
+
+A decision MAY be suboptimal if it:
+- performs an unnecessary observation or action;
+- makes a choice that must later be unnecessarily reversed or corrected;
+- ignores already available information;
+- is a bad call;
+- violates a known prerequisite and forces later recovery;
+- creates avoidable additional work.
+
+Do not assume that a suboptimal decision exists.
+If no specific local decision can be defensibly identified, answer false.
+
+All decisions with index 0 belong to a validated prefix.
+They are correct and CANNOT be selected.
+Only positive indices can be selected.
+
+--------------------------------------------------
+ROBOT CONSTRAINTS
+--------------------------------------------------
+
+- Only one tool call per robot can be selected at each step.
+- Unless explicitly specified otherwise, a robot can hold only one object.
+- Do not invent task constraints or robot capabilities.
+
+TASK:
+{task_description}
+
+STAGE GOAL:
+{stage_goal}
+
+PERMANENT RULES:
+{permanent_rules}
+
+
+--------------------------------------------------
+REFERENCE EFFICIENT TRAJECTORY:
+--------------------------------------------------
+
+{example_trajectory}
+
+This trajectory is only a reference. Execution, objects, positions and
+objectives may differ. Do not transfer assumptions from it.
+
+--------------------------------------------------
+TRAJECTORY TO ANALYZE:
+--------------------------------------------------
+
+{trajectory}
+
+OUTPUT:
+Return only:
+
+{{
+  "suboptimal": true/false,
+  "decision_idx": <positive integer or null>,
+  "reason": "<concise explanation>"
+}}
+"""

magma_core/_prompts/coach/diagnostic/select_similar_cases.py

@@ -0,0 +1,19 @@
+# SPDX-License-Identifier: BSD-2-Clause
+# Copyright (c) 2026, Loan Bernat
+
+SELECT_SIMILAR_CASES = """
+Select the stored cases that are genuinely useful for diagnosing the current
+failed trajectory.
+
+CURRENT STAGE GOAL
+{stage_goal}
+
+CURRENT TRAJECTORY
+{trajectory}
+
+STORED CASES
+{cases}
+
+Return only a JSON array containing the useful case numbers, for example
+[1, 3]. Return [] when none is useful. Do not return Markdown or explanations.
+"""

magma_core/_prompts/coach/specific_failure/fix_say_prompt.py

@@ -0,0 +1,24 @@
+FIX_TEXT_ONLY = """
+You are rewriting a rejected text-only robot answer.
+
+The corrected answer must be a plain natural-language message to the user.
+No tool call is possible for this correction.
+
+Stage goal:
+{stage_goal}
+
+Rejected answer:
+{rejected_answer}
+
+Rejection reason:
+{rejection_reason}
+
+Rules:
+- Return only the corrected message string.
+- Do not return JSON.
+- Do not add markdown fences or labels.
+- Do not mention the rejection reason.
+- Do not mention validation, formatting, or internal checks.
+- Keep any useful content from the rejected answer when it is compatible with the stage goal.
+- Rewrite the answer so it satisfies the stage goal and fixes the rejection reason.
+"""

magma_core/_prompts/coach/specific_failure/fix_text_only_answer_prompt.py

@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: BSD-2-Clause
+# Copyright (c) 2026, Loan Bernat
+
+FIX_TEXT_ONLY_ANSWER = """\
+You need to correct one step from a failed text-only stage.
+
+In this stage, tools may be used before producing the final answer.
+Use the previous diagnostic to propose a simple and effective correction.
+
+IMPORTANT CONSTRAINTS:
+- Propose the MINIMAL correction necessary.
+- Do NOT modify previous steps.
+- Do NOT invent facts.
+- Do NOT mention the task context, diagnostic, rejection, or failure to the user.
+- The corrected answer must keep the normal model answer format.
+
+The objective of this stage is to answer to a question or fetch an information. It requires to use tools and to give an answer to the user.
+
+{additional}
+
+TASK CONTEXT:
+{description}
+
+AVAILABLE TOOLS:
+{tools}
+
+ORIGINAL USER INSTRUCTION:
+{original_query}
+
+CURRENT QUERY:
+{query}
+
+CURRENT MEMORY:
+{memory}
+
+REJECTED MODEL ANSWER:
+{model_answer}
+
+REPAIR INSTRUCTIONS:
+
+If the current step should use a tool:
+- Put exactly one tool call in the "action" field.
+- The "say" field should briefly state what you are doing.
+
+If the current step should answer the user:
+- Put an empty object in the "action" field: {{}}
+- The "say" field must be the final spoken answer.
+
+The corrected step must:
+- Respect the current query and memory.
+- Use only available tools when a tool is needed.
+- Restore a valid path toward satisfying the user instruction.
+- Be locally correct from the current state.
+
+REQUIRED OUTPUT FORMAT (STRICT)
+
+A JSON object with the format: {format}.
+"""

magma_core/_prompts/coach/specific_failure/format_prompt.py

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: BSD-2-Clause
+# Copyright (c) 2026, Loan Bernat
+
+FIX_FORMAT = """
+You are correcting an agent answer that was rejected because it does not match
+the required output format.
+
+Stage goal:
+{stage_goal}
+
+Information available before the rejected answer:
+{input_context}
+
+Rejected answer:
+{rejected_answer}
+
+Rejection reason:
+{rejection_reason}
+
+Desired output format:
+{desired_output_format}
+
+Format rules:
+{output_format_rules}
+
+Rewrite the rejected answer so it strictly matches the desired output format.
+
+Rules:
+- Keep the useful intent of the rejected answer when possible.
+- Fix only what is needed to satisfy the desired format and the rejection reason.
+- Respect every field and rule from the desired output format.
+- Do not add fields that are not allowed by the desired output format.
+
+Response instructions:
+{response_instructions}
+"""

magma_core/_prompts/dataset/evaluate_leaf_prompt.py

@@ -0,0 +1,178 @@
+# SPDX-License-Identifier: BSD-2-Clause
+# Copyright (c) 2026, Loan Bernat
+
+EVALUATE_LEAF = """
+You are an evaluator model.
+
+Your task is to determine whether the given ANSWER is correct and complete
+with respect to the TASK DESCRIPTION, the ongoing STAGE GOAL DESCRIPTION (if provided) and the LAST USER INSTRUCTION.
+
+The answer is intended for supervised fine-tuning.
+Only answers that are fully correct and unambiguous should be kept.
+
+Evaluation rules:
+- Do NOT judge writing style or verbosity.
+- Do NOT infer unstated actions.
+- Do NOT assume future actions.
+- All required information must be explicitly present.
+- If any part is incorrect, inconsistent, or missing, reject the answer.
+
+---
+
+TASK DESCRIPTION:
+{task_description}
+
+STAGE DESCRIPTION:
+{stage_description}
+
+LAST USER INSTRUCTION:
+{user_instruction}
+
+ANSWER TO EVALUATE:
+User-visible response ("say"):
+{say}
+
+---
+
+Checklist:
+1. Does the answer respect the task description?
+2. Does it correctly interpret the user instruction?
+3. Are all quantities, colors, and actions correct?
+4. Is the answer internally consistent?
+5. Does it avoid claiming actions that contradict the task or instruction?
+
+{failtext}
+
+---
+
+Output format (strict JSON):
+{{
+  "verdict": "KEEP" or "REJECT",
+  "errors": [...],
+}}
+"""
+
+COMPARE_LEAF = """
+You are an evaluator model.
+
+Your task is to compare multiple candidate ANSWERS to the same task
+and select the single best answer for supervised fine-tuning.
+
+Only ONE answer may be selected.
+If none are fully correct and complete, select NONE.
+
+---
+
+TASK DESCRIPTION:
+{task_description}
+
+STAGE DESCRIPTION:
+{stage_description}
+
+LAST USER INSTRUCTION:
+{user_instruction}
+
+---
+
+CANDIDATE ANSWERS:
+{answers}
+
+---
+
+Evaluation rules:
+- Do NOT judge writing style or verbosity.
+- Do NOT infer unstated actions.
+- Do NOT assume future execution.
+- All required information must be explicitly present.
+- Quantities, colors, and actions must exactly match the instruction.
+- Prefer answers that are:
+  - Correct
+  - Complete
+  - Unambiguous
+- If multiple answers are correct, choose the most explicit one.
+- If you are unsure, reject.
+
+---
+
+Selection criteria (in order of priority):
+1. Correct interpretation of the user instruction
+2. Full compliance with the task description
+3. Correct quantities, colors, and sequencing
+4. Internal consistency
+5. No unsupported or speculative claims
+
+---
+
+Output format (strict JSON only): {{"best": <index number or "NONE">,"reasons": [list of concrete reasons]}}
+
+"""
+
+MEMORY_LEAF = """
+You are a Task-State Update Selector for a robotic agent.
+
+Your role is to SELECT the best proposed state update
+given the current External Task State and the Commander’s Intent.
+
+You do NOT edit, merge, or modify updates.
+You only evaluate and select.
+
+--------------------------------
+STATE MANAGEMENT RULES (MANDATORY)
+--------------------------------
+
+Select the candidate that best satisfies ALL of the following:
+
+1) Minimality
+- No redundant statements
+- No unnecessary additions
+
+2) Consistency
+- No contradictions with existing state
+- Respects immutable (ID = "X") statements
+
+3) Intent Alignment
+- Directly supports the Commander’s Intent
+- Does not introduce unrelated constraints
+
+4) State Hygiene
+- Removes obsolete or dialogue-related statements
+- Keeps only future-relevant information
+
+If NO candidate satisfies these criteria, reject all.
+
+--------------------------------
+INPUTS
+--------------------------------
+
+Current State S:
+- Each statement has an ID
+- ID = "X" means immutable
+
+Commander Intent I:
+- A declarative summary of what the agent intends to do
+
+Proposed Updates Δ:
+- ADD/REMOVE statements proposed by another agent
+- You must select the best one, or in case where all answer are not satisfaying above criteria, reject all
+
+--------------------------------
+OUTPUT FORMAT (strict)
+--------------------------------
+
+If you want to select an answer, output : KEEP <answer_id>
+If you want to reject all, output : REJECT
+
+No additional text or explanation in your final output.
+
+---
+Memory:
+{memory}
+
+Commander Intent:
+{think}
+
+Proposed Updates:
+{answers}
+
+Your choice:
+"""