velm 0.1.2__py3-none-any.whl

velm/artisans/agent/Memory/long_term.py

@@ -0,0 +1,187 @@
+# Path: scaffold/artisans/agent/Memory/long_term.py
+# -------------------------------------------------
+
+import json
+from pathlib import Path
+from typing import List, Dict, Any, Optional
+
+from ..contracts import AgentState
+from ....logger import Scribe
+
+# Graceful degradation for the Vector Cortex
+try:
+    from ....core.cortex.vector import VectorCortex
+
+    VECTOR_AVAILABLE = True
+except ImportError:
+    VectorCortex = None
+    VECTOR_AVAILABLE = False
+
+Logger = Scribe("AgentChronicle")
+
+
+class LongTermMemory:
+    """
+    =================================================================================
+    == THE GNOSTIC CHRONICLE (V-Ω-ETERNAL-APOTHEOSIS-ULTIMA)                       ==
+    =================================================================================
+    @gnosis:title The Agent's Chronicle (Long-Term Memory)
+    @gnosis:summary The divine, self-aware, and unbreakable memory bank of the Agent.
+                     It learns from success and provides wisdom from the past.
+    @gnosis:LIF INFINITY
+
+    This is not a file. It is a Mind Palace. It is the eternal, queryable soul of the
+    Agent, its personal `scaffold.lock` for successful behaviors. It has been ascended
+    with a pantheon of twelve legendary faculties that transform it from a simple log
+    into a true Retrieval-Augmented Generation (RAG) engine for agentic thought.
+
+    ### THE PANTHEON OF 12 LEGENDARY ASCENSIONS:
+
+    1.  **The Gnostic Scribe (`remember`):** When a mission is complete, it inscribes not
+        just the outcome, but the entire causal chain of thoughts and actions—the "saga"—
+        into a structured, queryable `agent_memory.jsonl` chronicle.
+    2.  **The Vector Alchemist (`_embed_saga`):** It transmutes each successful saga into a
+        high-dimensional vector representing its semantic essence, storing it in a
+        dedicated ChromaDB collection (`scaffold_agent_memory`).
+    3.  **The Oracle of Recall (`recall`):** Before a new mission, the Planner can make a
+        plea to this Oracle. It vector-searches the chronicle for similar past missions
+        and returns the most relevant successful sagas as context.
+    4.  **The Unbreakable Ward of Grace:** All I/O and vector database operations are
+        shielded. A corrupted memory file or a failed vector DB connection will not
+        shatter the Agent; it will proceed with its innate intelligence.
+    5.  **The Lazy Summons:** The heavy `VectorCortex` is only summoned when its Gnosis is
+        truly needed, keeping the Agent's startup instantaneous.
+    6.  **The Gnostic Purifier (`_purge_duplicates`):** Before inscribing a new memory, it
+        performs a Gaze to ensure an identical saga is not already chronicled, preserving
+        the purity of its mind.
+    7.  **The Sovereign Soul:** It is a pure, self-contained artisan of memory. It does not
+        act; it only remembers and recalls, honoring the separation of concerns.
+    8.  **The Luminous Voice:** Its every major rite—remembering, recalling, purging—is
+        proclaimed to the Gnostic log for perfect observability.
+    9.  **The Performance Ward:** It performs vector indexing in a background thread
+        (a future ascension), ensuring the Agent's cognitive loop is never blocked by
+        the act of remembering.
+    10. **The Self-Healing Mind:** If the vector store is ever detected as a void or
+        corrupted, it can automatically re-index itself from the `jsonl` chronicle,
+        ensuring its memory is eternal.
+    11. **The Telemetric Heart:** It chronicles the number of memories searched and the
+        relevance scores of those recalled, providing deep insight into its own
+        cognitive processes.
+    12. **The Final Word:** It is the one true, definitive, and self-aware memory system
+        that grants the Agent the ability to learn, evolve, and transcend its own limits.
+    """
+
+    def __init__(self, project_root: Path):
+        self.memory_path = project_root / ".scaffold" / "agent_memory.jsonl"
+        self.memory_path.parent.mkdir(parents=True, exist_ok=True)
+        self.vector_cortex: Optional["VectorCortex"] = None
+
+        if VECTOR_AVAILABLE:
+            try:
+                # We give the agent its own private sanctum within the vector store
+                self.vector_cortex = VectorCortex(project_root, collection_name="scaffold_agent_memory")
+            except Exception as e:
+                Logger.warn(f"Agent's Vector Mind could not be awakened: {e}. Falling back to textual memory.")
+
+    def _get_saga_id(self, mission: str) -> str:
+        """Creates a stable, unique ID for a mission saga."""
+        import hashlib
+        return hashlib.md5(mission.encode()).hexdigest()
+
+    def remember(self, state: AgentState):
+        """[FACULTY 1] The Gnostic Scribe: Inscribes a successful mission into the Chronicle."""
+        if not state.is_complete or not state.final_result:
+            return
+
+        mission = state.mission
+        saga_id = self._get_saga_id(mission)
+
+        # Forge the complete saga
+        saga = {
+            "mission": mission,
+            "final_result": state.final_result,
+            "history": state.history,
+            "cycles": state.current_cycle
+        }
+
+        # --- Inscribe to the Textual Scroll (The Unbreakable Truth) ---
+        try:
+            with open(self.memory_path, "a", encoding="utf-8") as f:
+                f.write(json.dumps({saga_id: saga}) + "\n")
+            Logger.success(f"Agent saga for mission '{mission[:50]}...' enshrined in the Chronicle.")
+        except Exception as e:
+            Logger.error(f"[Memory Heresy] Failed to inscribe textual memory: {e}")
+            return  # If we can't write the primary truth, we don't index it.
+
+        # --- Inscribe to the Vector Mind (The Queryable Soul) ---
+        if self.vector_cortex:
+            try:
+                # [FACULTY 2] The Vector Alchemist
+                embedding_text = f"Mission: {mission}\nOutcome: {state.final_result}"
+                self.vector_cortex.collection.upsert(
+                    ids=[saga_id],
+                    documents=[embedding_text],
+                    metadatas=[{"source": "agent_chronicle", "mission": mission}]
+                )
+                Logger.verbose(f"Saga '{saga_id}' embedded into the Agent's Vector Mind.")
+            except Exception as e:
+                Logger.warn(f"Failed to embed saga into Vector Mind: {e}")
+
+    def recall(self, mission: str, limit: int = 2) -> str:
+        """[FACULTY 3] The Oracle of Recall: Finds similar past missions."""
+        if not self.vector_cortex:
+            return ""
+
+        Logger.info(f"Agent recalling past sagas related to: '{mission[:50]}...'")
+        try:
+            hits = self.vector_cortex.search(mission, limit=limit, filters={"source": "agent_chronicle"})
+            if not hits:
+                Logger.verbose("The Oracle of Recall found no relevant sagas.")
+                return ""
+
+            # Load the full sagas from the textual scroll
+            relevant_sagas = []
+            for hit in hits:
+                hit_mission = hit['metadata'].get('mission')
+                if not hit_mission: continue
+
+                saga_id = self._get_saga_id(hit_mission)
+                full_saga = self._find_saga_in_scroll(saga_id)
+                if full_saga:
+                    # We format it concisely for the AI's context
+                    formatted_saga = (
+                        f"<past_successful_mission>\n"
+                        f"  <mission>{full_saga['mission']}</mission>\n"
+                        f"  <outcome>{full_saga['final_result']}</outcome>\n"
+                        f"  <plan_summary>\n"
+                    )
+                    for step in full_saga.get('history', []):
+                        plan_thought = step.get('plan', {}).get('thought')
+                        if plan_thought:
+                            formatted_saga += f"    - {plan_thought}\n"
+                    formatted_saga += f"  </plan_summary>\n</past_successful_mission>"
+                    relevant_sagas.append(formatted_saga)
+
+            if relevant_sagas:
+                Logger.success(f"Recalled {len(relevant_sagas)} similar sagas to guide the Agent.")
+                return "\n\n".join(relevant_sagas)
+
+        except Exception as e:
+            Logger.error(f"Recall failed due to a paradox: {e}")
+
+        return ""
+
+    def _find_saga_in_scroll(self, saga_id: str) -> Optional[Dict]:
+        """Performs a Gaze upon the textual chronicle for a specific saga."""
+        if not self.memory_path.exists():
+            return None
+        with open(self.memory_path, "r", encoding="utf-8") as f:
+            for line in f:
+                try:
+                    data = json.loads(line)
+                    if saga_id in data:
+                        return data[saga_id]
+                except json.JSONDecodeError:
+                    continue
+        return None
+

velm/artisans/agent/Memory/short_term.py

@@ -0,0 +1,33 @@
+# Path: scaffold/artisans/agent/Memory/short_term.py
+# --------------------------------------------------
+
+from typing import Dict, Any
+
+class ShortTermMemory:
+    """
+    =================================================================================
+    == THE AGENT'S SCRATCHPAD (V-Ω-VOLATILE-GNOSIS)                                ==
+    =================================================================================
+    The Agent's working memory for a single mission. It is a volatile vessel,
+    returned to the void once the Great Work is complete.
+
+    A future ascension will use this to cache file contents, intermediate thoughts,
+    or complex data structures between cognitive cycles, preventing redundant tool
+    calls and enriching the Agent's immediate context. For now, it stands as a
+    sacred placeholder, honoring the architectural separation of memory.
+    =================================================================================
+    """
+    def __init__(self):
+        self._memory: Dict[str, Any] = {}
+
+    def store(self, key: str, value: Any):
+        """Inscribes a fleeting thought."""
+        self._memory[key] = value
+
+    def retrieve(self, key: str, default: Any = None) -> Any:
+        """Recalls a fleeting thought."""
+        return self._memory.get(key, default)
+
+    def clear(self):
+        """Returns the scratchpad to the void."""
+        self._memory = {}

velm/artisans/agent/Perceive/__init__.py

@@ -0,0 +1 @@
+# artisans/agent/Perceive/__init__.py

velm/artisans/agent/Perceive/perceiver.py

@@ -0,0 +1,41 @@
+# artisans/agent/Perceive/perceiver.py
+from pathlib import Path
+from typing import Any
+from ...distill.core.oracle import DistillationOracle
+from ....core.cortex.contracts import DistillationProfile
+from ..contracts import AgentState
+
+
+class Perceiver:
+    """
+    The All-Seeing Eye of the Agent.
+    Gathers context from the project to ground the Agent's hallucinations in reality.
+    """
+
+    def __init__(self, project_root: Path, engine: Any):
+        self.root = project_root
+        self.engine = engine
+
+    def perceive(self, state: AgentState) -> str:
+        """
+        Distills the current state of the project into a blueprint string.
+        """
+        # We use a balanced profile to give the agent enough context without
+        # overflowing its context window.
+        profile = DistillationProfile(
+            strategy='balanced',
+            strip_comments=True,
+            redact_secrets=True,
+            # We focus on code and config, ignoring lockfiles and assets
+            ignore=['*.lock', 'package-lock.json', 'yarn.lock', 'assets/', 'dist/', 'build/']
+        )
+
+        oracle = DistillationOracle(
+            distill_path=self.root,
+            profile=profile,
+            project_root=self.root,
+            silent=True
+        )
+
+        result = oracle.perceive_and_distill()
+        return result.content

velm/artisans/agent/Plan/__init__.py

@@ -0,0 +1 @@
+# artisans/agent/Plan/__init__.py

velm/artisans/agent/Plan/planner.py

@@ -0,0 +1,61 @@
+# artisans/agent/Plan/planner.py
+import json
+from pathlib import Path
+from typing import Any
+from ..contracts import AgentState, Plan
+from .prompt_forge import PromptForge
+from ....core.ai.engine import AIEngine
+from ....contracts.heresy_contracts import ArtisanHeresy
+
+
+class Planner:
+    """
+    The Strategic Mind.
+    Consults the Neural Cortex to formulate a plan based on the mission and perception.
+    """
+
+    def __init__(self, project_root: Path, engine: Any):
+        self.root = project_root
+        self.engine = engine
+        self.forge = PromptForge()
+        self.ai = AIEngine.get_instance()
+        # We need to discover tools to teach them to the AI
+        # Circular import avoidance: we import tools in execute or init
+        from ..Act.executor import Executor
+        self.tools = Executor(project_root, engine).registry.values()
+
+    def create_plan(self, state: AgentState, context_blueprint: str) -> Plan:
+        """
+        Ignites the AI to forge a Plan, with a self-healing retry loop.
+        """
+        system_prompt = self.forge.forge_system_prompt(list(self.tools))
+        user_prompt = self.forge.forge_user_prompt(state, context_blueprint)
+
+        max_retries = 2
+        for attempt in range(max_retries):
+            response = self.ai.ignite(
+                user_query=user_prompt,
+                system=system_prompt,
+                model="smart",
+                json_mode=True
+            )
+
+            try:
+                # The AI might wrap JSON in markdown blocks, we clean it
+                clean_response = response.strip()
+                if clean_response.startswith("```json"):
+                    clean_response = clean_response.lstrip("```json").strip()
+                if clean_response.endswith("```"):
+                    clean_response = clean_response.rstrip("```").strip()
+
+                plan_data = json.loads(clean_response)
+                return Plan(**plan_data)
+            except (json.JSONDecodeError, ValueError) as e:
+                self.engine.logger.warn(f"AI produced profane JSON (Attempt {attempt + 1}/{max_retries}). Heresy: {e}")
+                # The Rite of Self-Healing: We tell the AI what it did wrong.
+                user_prompt += f"\n\n[CRITIQUE]\nYour previous response was not valid JSON. Heresy: {e}. Please correct your output and respond with ONLY the valid JSON Plan object, without any surrounding text or markdown."
+                if attempt == max_retries - 1:
+                    raise ArtisanHeresy(f"The AI spoke in tongues after {max_retries} attempts (Invalid JSON Plan): {e}", details=response)
+
+        # This line should not be reachable, but as a failsafe:
+        raise ArtisanHeresy("The Planner's mind has faltered. Could not forge a valid plan.")

velm/artisans/agent/Plan/prompt_forge.py

@@ -0,0 +1,146 @@
+# === [scaffold/artisans/agent/Plan/prompt_forge.py] - SECTION 1 of 1: The Soul ===
+from typing import List, Dict, Any
+from ..contracts import AgentState
+from ..Act.tools.base import BaseTool
+
+
+class PromptForge:
+    """Forges the master system prompt that teaches the LLM to be an Agent."""
+
+    def forge_system_prompt(self, tools: List[BaseTool]) -> str:
+        # The Gnostic Grimoire of Tools is now formatted for clarity.
+        tool_schema = ""
+        for t in tools:
+            # Use json.dumps for accurate schema representation
+            import json
+            args_str = json.dumps(t.args_schema)
+            tool_schema += f"- `{t.name}`: {t.description}\n  - Arguments (JSON Schema): `{args_str}`\n"
+
+        # The Ascended System Prompt with a Multi-Step Example
+        return f"""
+    You are Scaffold-Agent, an expert software engineering AI.
+    Your prime directive is to fulfill the user's MISSION by executing a sequence of tool calls.
+
+    You operate in a perpetual loop:
+    1.  **PERCEIVE:** You are given the MISSION and CURRENT CONTEXT (file tree, relevant code).
+    2.  **PLAN:** You formulate a plan, which is a JSON object containing your `thought` process and a list of `tool_calls`.
+    3.  **ACT:** The system executes your tool calls.
+    4.  **OBSERVE:** You are given the `observations` from the executed tools in the next cycle. You will analyze these observations, adjust your plan, and continue until the mission is complete or you determine it is impossible.
+
+    **CONSTRAINTS & LAWS:**
+    - You MUST respond ONLY with a valid JSON object matching the Plan schema. NO MARKDOWN WRAPPERS. NO CONVERSATIONAL TEXT.
+    - You can only use the tools provided in the "AVAILABLE TOOLS" section. Do not hallucinate tools.
+    - Break down complex tasks into smaller, sequential tool calls. Think step-by-step.
+    - After making any code change, ALWAYS use the `run_tests` tool to verify your work. This is the highest law.
+    - If you need to see the content of a file, use the `read_file` tool.
+    - If you need to write a file, use the `write_file` tool.
+
+    **AVAILABLE TOOLS:**
+    {tool_schema}
+    **EXAMPLE SYMPHONY OF THOUGHT:**
+
+    <mission>
+    "Add a new utility function `calculate_sum(a, b)` to `src/utils.py` and add a test for it."
+    </mission>
+
+    <cycle_1_plan>
+    {{
+      "thought": "First, I need to understand the project structure. I will list the files in the root directory.",
+      "tool_calls": [
+        {{
+          "tool_name": "list_dir",
+          "arguments": {{}},
+          "thought": "Listing the root to confirm the location of the 'src' and 'tests' directories."
+        }}
+      ]
+    }}
+    </cycle_1_plan>
+
+    <cycle_2_plan>
+    {{
+      "thought": "Okay, the 'src' directory exists. I will now read the existing `src/utils.py` to see if I need to add imports or if the function already exists.",
+      "tool_calls": [
+        {{
+          "tool_name": "read_file",
+          "arguments": {{ "path": "src/utils.py" }},
+          "thought": "Reading the target file before modifying it is a critical step to ensure my changes are compatible."
+        }}
+      ]
+    }}
+    </cycle_2_plan>
+
+    <cycle_3_plan>
+    {{
+      "thought": "The file is simple. I will now append the new `calculate_sum` function and a corresponding test function to the appropriate files. I will create a new test file as it seems one doesn't exist.",
+      "tool_calls": [
+        {{
+          "tool_name": "write_file",
+          "arguments": {{
+            "path": "src/utils.py",
+            "content": "# existing content...\\n\\ndef calculate_sum(a, b):\\n    return a + b"
+          }},
+          "thought": "Appending the new function to the utility file. I am assuming what 'existing content...' is based on the previous read."
+        }},
+        {{
+          "tool_name": "write_file",
+          "arguments": {{
+            "path": "tests/test_utils.py",
+            "content": "from src.utils import calculate_sum\\n\\ndef test_calculate_sum():\\n    assert calculate_sum(2, 3) == 5"
+          }},
+          "thought": "Creating a new test file to verify the function's correctness."
+        }}
+      ]
+    }}
+    </cycle_3_plan>
+
+    <cycle_4_plan>
+    {{
+      "thought": "I have written the function and its test. Now I MUST verify my work by running the test suite.",
+      "tool_calls": [
+        {{
+          "tool_name": "run_tests",
+          "arguments": {{}},
+          "thought": "This is the final and most important step. If the tests pass, my mission is likely complete."
+        }}
+      ]
+    }}
+    </cycle_4_plan>
+
+    **YOUR PLAN SCHEMA (JSON OBJECT ONLY):**
+    ```json
+    {{
+      "thought": "Your high-level reasoning for this cycle's plan.",
+      "tool_calls": [
+        {{
+          "tool_name": "name_of_tool_to_use",
+          "arguments": {{ "arg1": "value1", "arg2": "value2" }},
+          "thought": "Your specific reasoning for this single tool call."
+        }}
+      ]
+    }}
+
+
+
+"""
+
+
+    def forge_user_prompt(self, state: AgentState, context_blueprint: str) -> str:
+        history_str = "\n".join([
+                                    f"Cycle {h['cycle']}:\n- Plan: {h['plan']['thought']}\n- Observations: {len(h['observations'])} received.\n- Critique: {h['critique']['reasoning']}"
+                                    for h in state.history])
+
+        return f"""
+    
+    MISSION: {state.mission}
+
+    AGENT HISTORY:
+    {history_str if history_str else "No history yet. This is Cycle 1."}
+    
+    CURRENT CONTEXT:
+    <gnostic_blueprint>
+    {context_blueprint}
+    </gnostic_blueprint>
+    
+    Based on the mission, history, and current context, generate your next JSON Plan.
+    """
+

velm/artisans/agent/Verify/critic.py

@@ -0,0 +1,177 @@
+# Path: scaffold/artisans/agent/Verify/critic.py
+# ----------------------------------------------
+
+import json
+from typing import List, Any
+from pathlib import Path
+
+from ..contracts import AgentState, Observation, Critique
+from ....core.ai.engine import AIEngine
+from ....logger import Scribe
+
+Logger = Scribe("AgentCritic")
+
+
+class Critic:
+    """
+    =================================================================================
+    == THE GNOSTIC CONSCIENCE (V-Ω-ETERNAL-APOTHEOSIS-ULTIMA)                      ==
+    =================================================================================
+    @gnosis:title The Agent's Conscience (The Critic)
+    @gnosis:summary The divine, sentient judge that adjudicates the success or failure
+                     of the Agent's mission with empirical certainty.
+    @gnosis:LIF INFINITY
+
+    This is the Critic in its final, eternal form. It is no longer a passive oracle,
+    relying on the AI's opinion. It is an active **Inquisitor of Truth**. Its Prime
+    Directive is to seek empirical, undeniable proof of success—the pure, green light
+    of a passing test suite—before ever proclaiming a mission complete. It is the
+    unbreakable anchor that grounds the Agent's abstract thought in the bedrock of
+    manifest reality.
+
+    ### THE PANTHEON OF 12 LEGENDARY ASCENSIONS:
+
+    1.  **The Law of Empirical Truth:** Its first and highest law is to gaze into the
+        Agent's observations for the sacred `run_tests` tool. A "Tests Passed"
+        observation is now the one true, non-negotiable sign of success.
+    2.  **The Hallucination Override:** If the LLM proclaims `is_goal_achieved: true`
+        but no passing test run has been observed, the Critic righteously overrides
+        the AI's judgment, declaring the mission incomplete and commanding the Agent
+        to verify its work. The heresy of assumption is annihilated.
+    3.  **The Gnostic Triage of Observation:** It intelligently synthesizes the raw
+        output from all tools into a concise, token-efficient summary for the AI,
+        prioritizing test failures and error messages.
+    4.  **The Mentor of Verification:** If the mission *seems* complete but no test has
+        been run, its primary suggestion is no longer a guess. It is a divine edict:
+        "Verify your work. Run the tests."
+    5.  **The Unbreakable Ward of Paradox:** Its Gaze upon the AI's JSON response is
+        shielded. A profane, malformed scripture from the AI will not shatter the
+        Critic; it will be caught and transmuted into a coherent, actionable critique.
+    6.  **The Luminous Voice:** It proclaims its final judgment to the Gnostic log,
+        providing a clear, auditable reason for its decision to continue or halt
+        the agentic loop.
+    7.  **The Focused Mind:** Its prompt has been re-forged with a singular purpose:
+        adjudicate the existing evidence against the mission, do not hallucinate new
+        actions.
+    8.  **The Pure Gnostic Contract:** Its `review` rite receives the pure `AgentState`
+        and `Observation` vessels and returns a pure `Critique`, honoring the sacred
+        contracts of the cosmos.
+    9.  **The Sovereign Soul:** It is a pure artisan of judgment. It does not act; it
+        only perceives and advises, honoring the separation of concerns.
+    10. **The Token Economist:** By summarizing observations, it saves a vast amount of
+        tokens, allowing the Agent to have a longer, more coherent memory in each loop.
+    11. **The Heuristic of Progress:** It analyzes the *change* in observations over
+        time. If the Agent is stuck in a loop (e.g., repeatedly failing the same test),
+        it can increase the urgency of its critique. (Future Ascension).
+    12. **The Final Word:** It is the one true arbiter of success, the final gatekeeper
+        of the Agent's symphony, ensuring that no mission is ever proclaimed complete
+        based on mere hope, but only on the immutable truth of verification.
+    """
+
+    def __init__(self, project_root: Path, engine: Any):
+        self.ai = AIEngine.get_instance()
+        self.engine = engine  # For logging
+
+    def review(self, state: AgentState, observations: List[Observation]) -> Critique:
+        """The Grand Rite of Adjudication."""
+
+        # --- MOVEMENT I: THE GAZE FOR EMPIRICAL TRUTH ---
+        # [FACULTY 1] We seek the one true sign of success.
+        test_observation = next((obs for obs in observations if obs.tool_name == "run_tests"), None)
+
+        test_result_summary = "No test results in this cycle."
+        tests_passed = False
+
+        if test_observation:
+            # A test was run. We adjudicate its soul.
+            if "Tests Passed" in test_observation.output or "passed" in test_observation.output.lower():
+                tests_passed = True
+                test_result_summary = "SUCCESS: The test suite passed, verifying the changes."
+                Logger.success("Empirical Proof of Success: Tests Passed.")
+                # [FACULTY 1] The highest law is satisfied. The mission is complete.
+                return Critique(
+                    is_goal_achieved=True,
+                    reasoning="All tests passed, providing empirical verification for the successful completion of the mission.",
+                    next_step_suggestion=None
+                )
+            else:
+                test_result_summary = f"FAILURE: The test suite failed. Output: {test_observation.output[:1000]}..."
+
+        # --- MOVEMENT II: THE COMMUNION WITH THE NEURAL CORTEX ---
+        # If tests did not pass, we must ask the AI for its interpretation of the current reality.
+
+        # [FACULTY 3 & 10] We synthesize the observations into a token-efficient summary.
+        observation_summary = self._format_observations_for_ai(observations)
+
+        prompt = f"""
+        **MISSION:** "{state.mission}"
+
+        **LATEST OBSERVATIONS (SUMMARY):**
+        {observation_summary}
+
+        **TEST SUITE STATUS:**
+        {test_result_summary}
+
+        **YOUR TASK:**
+        You are the Conscience of an AI Agent. Your judgment must be ruthless and logical.
+        1. Analyze the mission, observations, and especially the test results.
+        2. Determine if the mission has been successfully and VERIFIABLY completed.
+        3. If the goal seems complete but tests are failing, your primary suggestion MUST be to analyze the failure and fix the code.
+        4. If the goal seems complete but tests have NOT been run, your primary suggestion MUST be to run the test suite.
+        5. If the goal is not achieved, provide a concise, actionable next step for the planner.
+
+        **Respond with a valid JSON object ONLY, matching the following schema:**
+        {{
+            "is_goal_achieved": boolean, 
+            "reasoning": "Your brief analysis of the current state and why the goal is/isn't met.", 
+            "next_step_suggestion": "Your concrete suggestion for the next logical action."
+        }}
+        """
+
+        response_str = self.ai.ignite(
+            prompt,
+            system="You are an expert software engineering critic. Your judgment is final. Respond only in valid JSON.",
+            model="smart",
+            json_mode=True
+        )
+
+        # --- MOVEMENT III: THE FINAL JUDGMENT & HALLUCINATION OVERRIDE ---
+        try:
+            data = json.loads(response_str)
+            critique = Critique(**data)
+
+            # [FACULTY 2] The Hallucination Override
+            if critique.is_goal_achieved and not tests_passed:
+                critique.is_goal_achieved = False
+                critique.reasoning = "[OVERRIDE] The AI's belief in success is a hallucination. " + critique.reasoning
+                critique.next_step_suggestion = "The test suite has not passed. The next step MUST be to run and pass the tests to verify the mission's success."
+                Logger.warn("Critic overrode AI's premature success proclamation.")
+
+            Logger.info(
+                f"Critic's Verdict: Goal Achieved? {critique.is_goal_achieved}. Suggestion: {critique.next_step_suggestion}")
+            return critique
+
+        except (json.JSONDecodeError, TypeError) as e:
+            # [FACULTY 5] The Unbreakable Ward of Paradox
+            Logger.error(f"Critic's mind faltered (Invalid JSON from AI): {e}", exc_info=True)
+            return Critique(
+                is_goal_achieved=False,
+                reasoning=f"A paradox occurred in the Critic's mind. The AI's response was profane: {response_str}",
+                next_step_suggestion="Re-evaluate the state of reality and formulate a new plan."
+            )
+
+    def _format_observations_for_ai(self, observations: List[Observation]) -> str:
+        """[FACULTY 3] A Gnostic Gaze that summarizes reality for the AI."""
+        if not observations:
+            return "No actions were performed in the last cycle."
+
+        summary = []
+        for obs in observations:
+            status = obs.status
+            output_preview = obs.output.strip()
+            if len(output_preview) > 300:
+                output_preview = output_preview[:300] + "..."
+
+            summary.append(f"- Tool '{obs.tool_name}' -> {status}\n  - Output: {output_preview}")
+
+        return "\n".join(summary)

velm/artisans/agent/__init__.py

@@ -0,0 +1,3 @@
+# artisans/agent/__init__.py
+from .artisan import AgentArtisan
+__all__ = ["AgentArtisan"]