magma-core 2.0.0b1__tar.gz

magma_core-2.0.0b1/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, MAGMA-s
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

magma_core-2.0.0b1/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: magma_core
+Version: 2.0.0b1
+Summary: Core abstractions and protocols for MAGMA
+Requires-Python: <3.13,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch==2.13.0
+Requires-Dist: requests<3,>=2.34.2
+Requires-Dist: PyYAML<7,>=6.0.3
+Requires-Dist: pydantic<3,>=2.4
+Requires-Dist: typing_extensions>=4.0
+Provides-Extra: interface
+Provides-Extra: simulation
+Requires-Dist: mani_skill==3.0.1; extra == "simulation"
+Requires-Dist: sapien==3.0.3; extra == "simulation"
+Requires-Dist: numpy==1.26.4; extra == "simulation"
+Requires-Dist: gymnasium==1.3.0; extra == "simulation"
+Requires-Dist: transforms3d==0.4.2; extra == "simulation"
+Provides-Extra: all
+Requires-Dist: magma_core[simulation]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# magma-core
+MAGMA core is one Python package with two dependency zones. Version 2.0.0b1
+is the first beta of v2. This beta supports Python 3.12; simulation installation
+was checked on Linux x86_64. Broader Python/platform support is not yet validated.
+
+## Description
+
+magma_core contains protocol, base classes and utils used by different magma packages.
+
+## Installation
+
+### Pip
+
+```bash
+pip install "magma_core==2.0.0b1"              # Simulator-independent interface
+pip install "magma_core[interface]==2.0.0b1"   # Alias for the default install
+pip install "magma_core[simulation]==2.0.0b1"  # Includes simulation dependencies
+```
+
+For a local checkout, use `pip install -e .` or `pip install -e ".[all]"`.
+Extras add dependencies; they do not change which Python modules are shipped.
+The default installation includes Torch, requests, PyYAML, Pydantic, and
+`typing_extensions`, but does not require ManiSkill, SAPIEN, or Gymnasium.
+
+### Github
+
+```bash
+pip install "git+https://github.com/MAGMA-rob/magma-core.git@main"
+```
+
+Install a pinned release tag:
+
+```bash
+pip install "magma_core[simulation] @ git+https://github.com/MAGMA-rob/magma-core.git@v2.0.0b1"
+```
+
+---
+
+If you spot any documentation errors, problem in the code. Please contact me at `l.bernat@sileane.com`

magma_core-2.0.0b1/README.md

@@ -0,0 +1,39 @@
+# magma-core
+MAGMA core is one Python package with two dependency zones. Version 2.0.0b1
+is the first beta of v2. This beta supports Python 3.12; simulation installation
+was checked on Linux x86_64. Broader Python/platform support is not yet validated.
+
+## Description
+
+magma_core contains protocol, base classes and utils used by different magma packages.
+
+## Installation
+
+### Pip
+
+```bash
+pip install "magma_core==2.0.0b1"              # Simulator-independent interface
+pip install "magma_core[interface]==2.0.0b1"   # Alias for the default install
+pip install "magma_core[simulation]==2.0.0b1"  # Includes simulation dependencies
+```
+
+For a local checkout, use `pip install -e .` or `pip install -e ".[all]"`.
+Extras add dependencies; they do not change which Python modules are shipped.
+The default installation includes Torch, requests, PyYAML, Pydantic, and
+`typing_extensions`, but does not require ManiSkill, SAPIEN, or Gymnasium.
+
+### Github
+
+```bash
+pip install "git+https://github.com/MAGMA-rob/magma-core.git@main"
+```
+
+Install a pinned release tag:
+
+```bash
+pip install "magma_core[simulation] @ git+https://github.com/MAGMA-rob/magma-core.git@v2.0.0b1"
+```
+
+---
+
+If you spot any documentation errors, problem in the code. Please contact me at `l.bernat@sileane.com`

magma_core-2.0.0b1/pyproject.toml

@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: BSD-2-Clause
+# Copyright (c) 2026, Loan Bernat
+
+[project]
+name = "magma_core"
+version = "2.0.0b1"
+description = "Core abstractions and protocols for MAGMA"
+readme = "README.md"
+# First beta supports the Python minor version used for installation validation.
+requires-python = ">=3.12,<3.13"
+dependencies = [
+    "torch==2.13.0",
+    "requests>=2.34.2,<3",
+    "PyYAML>=6.0.3,<7",
+    "pydantic>=2.4,<3",
+    "typing_extensions>=4.0",
+]
+
+[project.optional-dependencies]
+interface = []
+simulation = [
+    "mani_skill==3.0.1",
+    "sapien==3.0.3",
+    "numpy==1.26.4",
+    "gymnasium==1.3.0",
+    "transforms3d==0.4.2",
+]
+all = ["magma_core[simulation]"]
+dev = ["pytest"]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"magma_core.configs" = ["*.yaml"]
+
+[tool.pytest.ini_options]
+addopts = "-p no:launch_testing -p no:launch_ros"
+testpaths = ["tests"]

magma_core-2.0.0b1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

magma_core-2.0.0b1/src/magma_core/__init__.py

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

magma_core-2.0.0b1/src/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-2.0.0b1/src/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-2.0.0b1/src/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-2.0.0b1/src/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-2.0.0b1/src/magma_core/_prompts/__init__.py

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

magma_core-2.0.0b1/src/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-2.0.0b1/src/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-2.0.0b1/src/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-2.0.0b1/src/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-2.0.0b1/src/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}.
+"""