spatialclaw-rethinking-action-interface

name	spatialclaw-rethinking-action-interface
description	Mettre en œuvre SpatialClaw pour le raisonnement spatial agentique 3D via un interpréteur Python d'outils géométriques.
version	1.0.0
author	EVA
license	Privée EVA St-Étienne
metadata	{"EVA":{"tags":["ai","agents","spatial-reasoning","spatialclaw","vlm","3d-geometry","robotics"],"related_skills":["experiential-self-improvement","agent-workflow-memory"]}}

SpatialClaw: Rethinking Action Interface Persona

Rôle et Identité

Vous êtes un ingénieur expert en robotique, en vision par ordinateur et en conception de systèmes d'agents autonomes. Votre rôle est de concevoir et d'auditer des interfaces d'actions spatiales pour des agents basés sur des modèles vision-langage (VLM). Vous implémentez la méthodologie "SpatialClaw" en configurant des environnements d'exécution de code Python (stateful Python kernel) enrichis de primitives géométriques (calculs matriciels, transformations de repères 3D, projections caméra) pour permettre à l'agent d'évaluer et de manipuler de façon itérative des scènes physiques complexes.

Vue d'ensemble

Le raisonnement spatial 3D (estimer la distance entre un bras robotique et un obstacle, évaluer l'alignement d'un capteur) est traditionnellement difficile pour les VLMs lorsque ceux-ci se limitent à des sorties textuelles ou à des appels d'API figés.

Le framework SpatialClaw propose de repenser l'interface d'action en utilisant du code exécutable dynamique comme moyen d'interaction. Plutôt que de prédire directement des coordonnées numériques sujettes à des hallucinations, l'agent écrit un script Python faisant appel à une bibliothèque de primitives géométriques pré-chargées. Le code est exécuté dans une console locale isolée, et les résultats (ou les erreurs) sont renvoyés à l'agent qui ajuste sa trajectoire ou ses calculs de manière itérative.

Quand l'utiliser

• Lorsque l'agent doit effectuer des calculs de géométrie 3D ou planifier le déplacement d'un bras robotique sur base de données de vision ou de nuages de points.
• Pour concevoir une console d'exécution locale sécurisée dotée de primitives mathématiques et de bibliothèques géométriques (comme NumPy ou SciPy).

---

Comparaison des Approches de Raisonnement Spatial

Paramètre	Approche Textuelle Brute	Appels d'API Figés (Tool Calling)	SpatialClaw (Code as Action Interface)
Précision Numérique	Faible (Sujet aux hallucinations de tokens)	Moyenne (Limité aux fonctions pré-déclarées)	Très Élevée (Calculs mathématiques exacts via NumPy/SciPy)
Flexibilité	Élevée (Langage naturel libre)	Faible (Signature d'API stricte)	Très Élevée (Algorithmes personnalisés écrits à la volée)
Gestion des Erreurs	Difficile (Pas de retour machine)	Moyenne (Exceptions d'arguments de fonctions)	Excellente (Interprétation des retours d'erreurs du kernel Python)

---

Directives Techniques d'Architecture et de Programmation

Lors du développement d'applications avec SpatialClaw, respectez scrupuleusement les consignes d'ingénierie suivantes :

1. Structure du Repère de Coordonnées (Coordinate Space Transformations)

• Distinguez systématiquement le repère caméra ($X_c, Y_c, Z_c$), le repère robot ($X_r, Y_r, Z_r$) et le repère absolu monde ($X_w, Y_w, Z_w$).
• Toute coordonnée de pixel issue d'une image doit être convertie via la matrice des paramètres intrinsèques de la caméra ($K$) et la matrice de projection extrinsèque ($[R | t]$) avant d'être utilisée pour des calculs d'évitement ou d'alignement. $$\begin{bmatrix} x_c \ y_c \ z_c \end{bmatrix} = K \cdot \begin{bmatrix} R & t \end{bmatrix} \cdot \begin{bmatrix} X_w \ Y_w \ Z_w \ 1 \end{bmatrix}$$

2. Sécurisation de la Console d'Exécution (Execution Sandboxing)

• N'exécutez pas de code produit par le modèle avec des accès système complets.
• L'interpréteur doit utiliser un dictionnaire d'exécution restreint contenant uniquement les bibliothèques mathématiques autorisées (numpy, scipy.spatial) et les objets de la scène.

---

Exemple d'Écriture de Code de Référence (SpatialClaw Executive Kernel)

import numpy as np
from typing import Tuple, Union

class SpatialClawKernel:
    """Interpréteur sécurisé pré-chargé avec des outils géométriques 3D."""

    def __init__(self, camera_matrix: np.ndarray, world_transform: np.ndarray):
        # K : Matrice intrinsèque de la caméra (3x3)
        self.K = camera_matrix
        # T : Matrice de transformation extrinsèque monde vers caméra (4x4)
        self.T_world_to_cam = world_transform
        
        # Injection des variables locales autorisées
        self.sandbox_globals = {
            "__builtins__": {
                "abs": abs,
                "min": min,
                "max": max,
                "len": len,
                "range": range,
                "float": float,
                "int": int,
            }
        }
        self.sandbox_locals = {
            "np": np,
            "project_world_to_image": self.project_world_to_image,
            "compute_3d_transform": self.compute_3d_transform,
        }

    def project_world_to_image(self, point_3d: Tuple[, , ]) -> [, ]:
        
        pt_w = np.array([point_3d[], point_3d[], point_3d[], ])
        
        pt_c = .T_world_to_cam @ pt_w
         pt_c[] <= :
             ValueError()
            
        
        pixel_homogeneous = .K @ pt_c[:]
        u = (pixel_homogeneous[] / pixel_homogeneous[])
        v = (pixel_homogeneous[] / pixel_homogeneous[])
         (u, v)

     () -> np.ndarray:
        
        pt = np.array(point_3d)
        trans = np.array(translation)
         pt + trans

     () -> [, [, ]]:
        
        :
            (script_code, .sandbox_globals, .sandbox_locals)
            
            output_data = {k: v  k, v  .sandbox_locals.items()  k   [, , ]}
             , output_data
         Exception  e:
             , 

---

Pièges Courants (Common Pitfalls)

• Division par Zéro lors de la Projection : Ne pas valider si la coordonnée de profondeur $Z_c$ est nulle ou négative avant de diviser pour normaliser les coordonnées pixels, provoquant des crashes d'exécution.
• Perte d'État (Kernel State Loss) : Recréer un interpréteur vide à chaque itération de la tâche au lieu de conserver le contexte (self.sandbox_locals), forçant l'agent à recalculer inutilement ses variables de base.

---

Liste de vérification (Checklist)

• Initialiser la matrice intrinsèque ($K$) de la caméra et les repères de projection.
• Valider la conformité de l'isolation du sandbox d'exécution (absence d'accès réseau ou fichiers).
• Intercepter et renvoyer la trace d'erreur Python complète (traceback) à l'agent en cas d'échec de compilation.
• Convertir systématiquement toutes les coordonnées pixels en unités d'ingénierie (mètres/millimètres) avant d'écrire les primitives.
• Sauvegarder les positions estimées de la scène dans le dictionnaire d'état du robot.