continuum-toolkit 1.0.0__py3-none-any.whl

handoff/adapters/claude_adapter.py

@@ -0,0 +1,176 @@
+"""
+Project Continuum - Claude Handoff Adapter
+==========================================
+Milestone 6 - Phase 15: Model-Specific Handoff Adapters.
+Formats handoff packages with semantic XML tags (<project_state>, <verified_reality>,
+<active_blockers>, <tactical_tasks>) optimized for Claude 3 / 3.5 prompt caching and reasoning.
+"""
+
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+from core.enums import TargetModel, Status
+from core.serializer import CanonicalStateSerializer
+from core.state_models import CanonicalProjectState
+from handoff.adapters.base import BaseModelAdapter
+
+
+class ClaudeAdapter(BaseModelAdapter):
+    """
+    Handoff adapter tailored for Anthropic's Claude models.
+    Uses structured XML tags for optimal context separation and prompt caching.
+    """
+
+    def __init__(self):
+        super().__init__(target_model=TargetModel.CLAUDE)
+
+    def generate_handoff(
+        self,
+        canonical_state: CanonicalProjectState,
+        context_selection: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, str]:
+        # 1. project-state.json
+        state_json = CanonicalStateSerializer.to_json(canonical_state, indent=2)
+
+        # 2. project-context.md (XML structured)
+        context_md = self._build_claude_context(canonical_state)
+
+        # 3. handoff.md (XML tagged continuation briefing)
+        handoff_md = self._build_claude_handoff(canonical_state, context_selection)
+
+        return {
+            "project-state.json": state_json,
+            "project-context.md": context_md,
+            "handoff.md": handoff_md
+        }
+
+    def _build_claude_context(self, state: CanonicalProjectState) -> str:
+        p_state = state.project_state
+        lines = [
+            f"# Project Continuum — Architectural Context for Claude",
+            f"<project_metadata>",
+            f"  <project_id>{state.project_id}</project_id>",
+            f"  <schema_version>{state.schema_version}</schema_version>",
+            f"  <root_path>{p_state.root_path}</root_path>",
+            f"  <languages>{', '.join(p_state.detected_languages)}</languages>",
+            f"  <build_status>{p_state.build_status.value}</build_status>",
+            f"</project_metadata>",
+            "",
+            "<verified_architecture>",
+        ]
+
+        for n in state.graph_nodes.values():
+            lines.append(
+                f"  <component id=\"{n.id}\" type=\"{n.node_type.value}\" status=\"{n.status.value}\" confidence=\"{n.confidence_score:.0f}%\">"
+                f"{n.name}</component>"
+            )
+
+        lines.extend([
+            "</verified_architecture>",
+            "",
+            "<test_verification_baseline>",
+        ])
+
+        for t in p_state.test_results:
+            err_tag = f" error=\"{t.error_message}\"" if t.error_message else ""
+            lines.append(
+                f"  <test id=\"{t.test_id}\" suite=\"{t.suite}\" status=\"{t.status.value}\" exit_code=\"{t.exit_code}\"{err_tag}>"
+                f"{t.name}</test>"
+            )
+
+        lines.extend([
+            "</test_verification_baseline>",
+            "",
+            "<architectural_constraints>",
+        ])
+
+        for c in self._extract_constraints(state):
+            lines.append(f"  <constraint>{c}</constraint>")
+
+        lines.append("</architectural_constraints>")
+        return "\n".join(lines)
+
+    def _build_claude_handoff(
+        self,
+        state: CanonicalProjectState,
+        context_selection: Optional[Dict[str, Any]] = None
+    ) -> str:
+        exec_state = state.agent_execution_state
+        c_state = state.conversational_state
+
+        lines = [
+            "# Project Continuum — AI Agent Continuation Handoff",
+            "",
+            "<!-- CONTINUUM_HANDOFF_METADATA",
+            "Target-Model: ANTHROPIC_CLAUDE",
+            "Format: XML_TAGGED_ONTOLOGY",
+            f"Generated-At: {datetime.now(timezone.utc).isoformat()}",
+            "-->",
+            "",
+            "> 🧠 **CONTINUUM AI HANDOFF NOTICE:**",
+            "> You are taking over this ongoing software engineering project.",
+            "> This handoff package was generated directly from physical workspace AST analysis & test verification.",
+            "> Follow the structured `<system_directives>` and `<recommended_next_action>` below.",
+            "",
+            "<system_directives>",
+            "  <directive>Preserve strict ontological separation between physical facts and conversational claims.</directive>",
+            "  <directive>Never assume unverified agent claims are physically implemented without test verification.</directive>",
+            "  <directive>Target format recognized: Anthropic Claude / XML Architecture.</directive>",
+            "</system_directives>",
+            "",
+            "<active_tasks>",
+        ]
+
+        if exec_state.active_tasks:
+            for t in exec_state.active_tasks:
+                files_str = ", ".join(t.target_files) if t.target_files else "none"
+                lines.append(f"  <task id=\"{t.id}\" status=\"{t.status.value}\" files=\"{files_str}\">{t.title}</task>")
+        else:
+            lines.append("  <task status=\"NONE\">No active in-flight tasks.</task>")
+
+        lines.extend([
+            "</active_tasks>",
+            "",
+            "<recommended_next_action>",
+        ])
+
+        if exec_state.next_action:
+            na = exec_state.next_action
+            lines.append(f"  <action type=\"{na.action_type}\" target=\"{na.target_uri}\">")
+            lines.append(f"    <description>{na.description}</description>")
+            if na.prerequisites:
+                lines.append(f"    <prerequisites>{', '.join(na.prerequisites)}</prerequisites>")
+            lines.append("  </action>")
+        else:
+            lines.append("  <action type=\"CONTINUE\">Resume highest priority in-progress component.</action>")
+
+        lines.extend([
+            "</recommended_next_action>",
+            "",
+            "<active_blockers_and_contradictions>",
+        ])
+
+        active_contra = self._extract_active_contradictions(state)
+        if active_contra:
+            for c in active_contra:
+                lines.append(f"  <contradiction id=\"{c['id']}\" severity=\"{c['severity']}\">")
+                lines.append(f"    <explanation>{c['explanation']}</explanation>")
+                lines.append(f"    <claim>{c['claim_text']}</claim>")
+                lines.append("  </contradiction>")
+        else:
+            lines.append("  <none>Zero unresolved contradictions detected.</none>")
+
+        lines.extend([
+            "</active_blockers_and_contradictions>",
+            "",
+            "<unverified_agent_claims>",
+        ])
+
+        for cl in c_state.agent_claims:
+            lines.append(
+                f"  <claim id=\"{cl.id}\" source=\"{cl.source_agent}\" status=\"{cl.claimed_status.value}\">"
+                f"{cl.claim_text}</claim>"
+            )
+
+        lines.append("</unverified_agent_claims>")
+        return "\n".join(lines)

handoff/adapters/codex_gpt_adapter.py

@@ -0,0 +1,151 @@
+"""
+Project Continuum - Codex / GPT Handoff Adapter
+================================================
+Milestone 6 - Phase 15: Model-Specific Handoff Adapters.
+Formats handoff packages with high-contrast Markdown, code fences, and explicit
+task checklists tailored for OpenAI GPT-4 / Codex reasoning engines.
+"""
+
+from typing import Any, Dict, Optional
+
+from core.enums import TargetModel, Status
+from core.serializer import CanonicalStateSerializer
+from core.state_models import CanonicalProjectState
+from handoff.adapters.base import BaseModelAdapter
+
+
+class CodexGptAdapter(BaseModelAdapter):
+    """
+    Handoff adapter tailored for OpenAI Codex / GPT-4 family models.
+    Uses Markdown headers, code block fencing, and structured step-by-step checklists.
+    """
+
+    def __init__(self):
+        super().__init__(target_model=TargetModel.CODEX_GPT)
+
+    def generate_handoff(
+        self,
+        canonical_state: CanonicalProjectState,
+        context_selection: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, str]:
+        state_json = CanonicalStateSerializer.to_json(canonical_state, indent=2)
+        context_md = self._build_gpt_context(canonical_state)
+        handoff_md = self._build_gpt_handoff(canonical_state, context_selection)
+
+        return {
+            "project-state.json": state_json,
+            "project-context.md": context_md,
+            "handoff.md": handoff_md
+        }
+
+    def _build_gpt_context(self, state: CanonicalProjectState) -> str:
+        p_state = state.project_state
+        lines = [
+            f"# Project Continuum — Verified Context for Codex/GPT",
+            f"```json",
+            f"{{",
+            f'  "project_id": "{state.project_id}",',
+            f'  "root_path": "{p_state.root_path}",',
+            f'  "build_status": "{p_state.build_status.value}"',
+            f"}}",
+            f"```",
+            "",
+            "## Verified Component Directory",
+        ]
+
+        for n in state.graph_nodes.values():
+            badge = "✅" if n.status == Status.VERIFIED else "⚠️"
+            lines.append(f"- {badge} **`{n.name}`** (`{n.id}`): Status `{n.status.value}` (Confidence: {n.confidence_score:.0f}%)")
+
+        lines.extend([
+            "",
+            "## Automated Test Suite Baseline",
+        ])
+
+        for t in p_state.test_results:
+            icon = "PASS" if t.status == Status.VERIFIED else "FAIL"
+            err = f" -> Error: {t.error_message}" if t.error_message else ""
+            lines.append(f"- `[{icon}]` `{t.name}` in `{t.suite}` (Exit code: {t.exit_code}){err}")
+
+        lines.extend([
+            "",
+            "## Inviolable Architectural Constraints",
+        ])
+
+        for c in self._extract_constraints(state):
+            lines.append(f"- [x] **CONSTRAINT**: {c}")
+
+        return "\n".join(lines)
+
+    def _build_gpt_handoff(
+        self,
+        state: CanonicalProjectState,
+        context_selection: Optional[Dict[str, Any]] = None
+    ) -> str:
+        exec_state = state.agent_execution_state
+        c_state = state.conversational_state
+
+        lines = [
+            "# Project Continuum — OpenAI Codex / GPT Continuity Task Plan",
+            "",
+            "<!-- CONTINUUM_HANDOFF_METADATA",
+            "Target-Model: OPENAI_CODEX_GPT",
+            "Format: MARKDOWN_CHECKLISTS_AND_CODEBLOCKS",
+            "-->",
+            "",
+            "> 🧠 **CONTINUUM AI HANDOFF NOTICE:**",
+            "> You are taking over an ongoing software engineering project.",
+            "> Ground truth is defined by physical AST code and test results, NOT past conversational assertions.",
+            "",
+            "### 🚨 System Protocol",
+            "1. You are picking up an ongoing engineering task.",
+            "2. Ground truth is defined by physical tests and code, NOT previous assistant chat messages.",
+            "3. Resolve blockers first before proceeding.",
+            "",
+            "## 📋 Active Tasks & Next Steps",
+        ]
+
+        if exec_state.active_tasks:
+            for t in exec_state.active_tasks:
+                lines.append(f"- [ ] **Task**: `{t.title}` (`{t.id}`) - Status: `{t.status.value}`")
+                if t.target_files:
+                    lines.append(f"  - Target files: {', '.join(f'`{f}`' for f in t.target_files)}")
+        else:
+            lines.append("- [ ] No in-flight tasks recorded.")
+
+        lines.extend([
+            "",
+            "## 🎯 Actionable Next Instruction",
+        ])
+
+        if exec_state.next_action:
+            na = exec_state.next_action
+            lines.append(f"**Action**: `{na.action_type}` on `{na.target_uri}`")
+            lines.append(f"**Details**: {na.description}")
+            if na.prerequisites:
+                lines.append(f"**Prerequisites**: {', '.join(f'`{p}`' for p in na.prerequisites)}")
+        else:
+            lines.append("**Action**: Resume highest priority unfinished component.")
+
+        lines.extend([
+            "",
+            "## 🔴 Unresolved Blockers & Discrepancy Register",
+        ])
+
+        active_contra = self._extract_active_contradictions(state)
+        if active_contra:
+            for c in active_contra:
+                lines.append(f"- ❌ **[{c['severity']} BLOCKER]**: {c['explanation']}")
+                lines.append(f"  - Claim: \"{c['claim_text']}\"")
+        else:
+            lines.append("- ✅ No active contradictions detected.")
+
+        lines.extend([
+            "",
+            "## 💬 Unverified Conversational Statements (Level 5)",
+        ])
+
+        for cl in c_state.agent_claims:
+            lines.append(f"- *Unverified Claim*: \"{cl.claim_text}\" (Agent: `{cl.source_agent}`)")
+
+        return "\n".join(lines)

handoff/adapters/gemini_adapter.py

@@ -0,0 +1,151 @@
+"""
+Project Continuum - Gemini Handoff Adapter
+==========================================
+Milestone 6 - Phase 15: Model-Specific Handoff Adapters.
+Formats handoff packages with deep hierarchical structures, ontological groupings,
+and rich contextual linkages optimized for Google Gemini 1.5 Pro / Flash large context windows.
+"""
+
+from typing import Any, Dict, Optional
+
+from core.enums import TargetModel, Status
+from core.serializer import CanonicalStateSerializer
+from core.state_models import CanonicalProjectState
+from handoff.adapters.base import BaseModelAdapter
+
+
+class GeminiAdapter(BaseModelAdapter):
+    """
+    Handoff adapter tailored for Google Gemini models.
+    Leverages deep hierarchical ontology representation and comprehensive cross-referencing.
+    """
+
+    def __init__(self):
+        super().__init__(target_model=TargetModel.GEMINI)
+
+    def generate_handoff(
+        self,
+        canonical_state: CanonicalProjectState,
+        context_selection: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, str]:
+        state_json = CanonicalStateSerializer.to_json(canonical_state, indent=2)
+        context_md = self._build_gemini_context(canonical_state)
+        handoff_md = self._build_gemini_handoff(canonical_state, context_selection)
+
+        return {
+            "project-state.json": state_json,
+            "project-context.md": context_md,
+            "handoff.md": handoff_md
+        }
+
+    def _build_gemini_context(self, state: CanonicalProjectState) -> str:
+        p_state = state.project_state
+        lines = [
+            f"# Project Continuum — Hierarchical Project Knowledge Graph (Gemini Engine)",
+            f"**Canonical State Container:** `{state.project_id}` (Schema: `{state.schema_version}`)",
+            "",
+            "## Tier 1: Ground Truth Project Topology",
+            "### Physical Environment & Manifests",
+            f"- Path: `{p_state.root_path}`",
+            f"- Polyglot Stack: {', '.join(p_state.detected_languages)}",
+            f"- Build Status: `[{p_state.build_status.value}]`",
+            "",
+            "### Domain Component Graph",
+        ]
+
+        for n in state.graph_nodes.values():
+            lines.append(f"- **{n.name}** (`{n.id}`) — Type: `{n.node_type.value}`, State: `{n.status.value}`, Verified Confidence: `{n.confidence_score:.1f}%`")
+
+        lines.extend([
+            "",
+            "## Tier 2: Empirical Verification & Evidence Matrix",
+            f"Total Verifiable Test Runs: {len(p_state.test_results)}",
+        ])
+
+        for t in p_state.test_results:
+            status_symbol = "🟢" if t.status == Status.VERIFIED else "🔴"
+            lines.append(f"{status_symbol} **{t.name}** (`{t.suite}`) | Exit Code: {t.exit_code} | Duration: {t.duration_ms:.1f}ms")
+            if t.error_message:
+                lines.append(f"   ↳ *Failure Reason:* `{t.error_message}`")
+
+        lines.extend([
+            "",
+            "## Tier 3: Invariant Architectural Principles",
+        ])
+
+        for c in self._extract_constraints(state):
+            lines.append(f"• **Hard Constraint:** {c}")
+
+        return "\n".join(lines)
+
+    def _build_gemini_handoff(
+        self,
+        state: CanonicalProjectState,
+        context_selection: Optional[Dict[str, Any]] = None
+    ) -> str:
+        exec_state = state.agent_execution_state
+        c_state = state.conversational_state
+
+        lines = [
+            "# Project Continuum — Google Gemini Agent Handoff & Continuity Instruction",
+            "",
+            "<!-- CONTINUUM_HANDOFF_METADATA",
+            "Target-Model: GOOGLE_GEMINI",
+            "Format: HIERARCHICAL_ONTOLOGY_TREE",
+            "-->",
+            "",
+            "> 🧠 **CONTINUUM AI HANDOFF NOTICE:**",
+            "> You are continuing an ongoing software engineering project with verified physical context.",
+            "",
+            "> 📌 **Epistemic Principle:**",
+            "> Strict demarcation between empirical facts (code, tests) and linguistic assertions (chat claims).",
+            "> Do not hallucinate task completion based on unverified conversational assertions.",
+            "",
+            "## 1. Tactical Execution Queue",
+        ]
+
+        if exec_state.active_tasks:
+            for t in exec_state.active_tasks:
+                lines.append(f"* **Active Task [{t.status.value}]:** `{t.title}` (`{t.id}`)")
+                if t.target_files:
+                    lines.append(f"  * Scoped Files: {', '.join(f'`{f}`' for f in t.target_files)}")
+        else:
+            lines.append("* *No in-flight tactical tasks.*")
+
+        lines.extend([
+            "",
+            "## 2. Deterministic Next Action",
+        ])
+
+        if exec_state.next_action:
+            na = exec_state.next_action
+            lines.append(f"* **Type:** `{na.action_type}`")
+            lines.append(f"* **Target:** `{na.target_uri}`")
+            lines.append(f"* **Description:** {na.description}")
+            if na.prerequisites:
+                lines.append(f"* **Prerequisites:** {', '.join(f'`{p}`' for p in na.prerequisites)}")
+        else:
+            lines.append("* **Type:** `RESUME_PRIORITY_TASK`")
+
+        lines.extend([
+            "",
+            "## 3. Discrepancy & Contradiction Registry",
+        ])
+
+        active_contra = self._extract_active_contradictions(state)
+        if active_contra:
+            for c in active_contra:
+                lines.append(f"* ⚠️ **[{c['severity']}] Discrepancy:** {c['explanation']}")
+                lines.append(f"  * Conflicting Assertion: \"{c['claim_text']}\"")
+        else:
+            lines.append("* ✅ *No unresolved discrepancies found.*")
+
+        lines.extend([
+            "",
+            "## 4. Subjective Claims Register (Level 5)",
+        ])
+
+        for cl in c_state.agent_claims:
+            lines.append(f"* *Claim:* \"{cl.claim_text}\" (Agent: `{cl.source_agent}`, Claimed: `[{cl.claimed_status.value}]`)")
+
+        return "\n".join(lines)

handoff/adapters/local_model_adapter.py

@@ -0,0 +1,130 @@
+"""
+Project Continuum - Local LLM Handoff Adapter
+==============================================
+Milestone 6 - Phase 15: Model-Specific Handoff Adapters.
+Formats handoff packages in high-density, compact token-budget-optimized formats
+for local models (e.g. Llama-3, Mistral, Qwen, DeepSeek Coder) with smaller context windows.
+"""
+
+from typing import Any, Dict, Optional
+
+from core.enums import TargetModel, Status
+from core.serializer import CanonicalStateSerializer
+from core.state_models import CanonicalProjectState
+from handoff.adapters.base import BaseModelAdapter
+
+
+class LocalModelAdapter(BaseModelAdapter):
+    """
+    Handoff adapter tailored for local open-source LLMs.
+    Prioritizes maximum information density and token frugality while strictly
+    preserving Tier 1 constraints, blockers, and next actions.
+    """
+
+    def __init__(self):
+        super().__init__(target_model=TargetModel.LOCAL_LLM)
+
+    def generate_handoff(
+        self,
+        canonical_state: CanonicalProjectState,
+        context_selection: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, str]:
+        # Compact JSON serialization (no extra whitespace)
+        state_json = CanonicalStateSerializer.to_json(canonical_state, indent=2)
+        context_md = self._build_compact_context(canonical_state)
+        handoff_md = self._build_compact_handoff(canonical_state, context_selection)
+
+        return {
+            "project-state.json": state_json,
+            "project-context.md": context_md,
+            "handoff.md": handoff_md
+        }
+
+    def _build_compact_context(self, state: CanonicalProjectState) -> str:
+        p_state = state.project_state
+        lines = [
+            f"# Context: {state.project_id} | Root: {p_state.root_path} | Build: [{p_state.build_status.value}]",
+            "",
+            "## Components",
+        ]
+
+        for n in state.graph_nodes.values():
+            lines.append(f"- {n.name}({n.id}): [{n.status.value}] ({n.confidence_score:.0f}%)")
+
+        lines.extend([
+            "",
+            "## Test Baseline",
+        ])
+
+        for t in p_state.test_results:
+            err = f" Err:{t.error_message}" if t.error_message else ""
+            lines.append(f"- {t.name}: [{t.status.value}] code:{t.exit_code}{err}")
+
+        lines.extend([
+            "",
+            "## Active Constraints",
+        ])
+
+        for c in self._extract_constraints(state):
+            lines.append(f"- ! {c}")
+
+        return "\n".join(lines)
+
+    def _build_compact_handoff(
+        self,
+        state: CanonicalProjectState,
+        context_selection: Optional[Dict[str, Any]] = None
+    ) -> str:
+        exec_state = state.agent_execution_state
+        c_state = state.conversational_state
+
+        lines = [
+            f"# Handoff | PrevAgent: {exec_state.model_name}",
+            "! RULE: Physical reality overrides chat claims. Tests define ground truth.",
+            "",
+            "## In-Flight Tasks",
+        ]
+
+        if exec_state.active_tasks:
+            for t in exec_state.active_tasks:
+                files = f" files={','.join(t.target_files)}" if t.target_files else ""
+                lines.append(f"- [{t.status.value}] {t.title} ({t.id}){files}")
+        else:
+            lines.append("- (none)")
+
+        lines.extend([
+            "",
+            "## Next Action",
+        ])
+
+        if exec_state.next_action:
+            na = exec_state.next_action
+            lines.append(f"- Action: {na.action_type} | Target: {na.target_uri}")
+            lines.append(f"  Note: {na.description}")
+        else:
+            lines.append("- Action: Continue incomplete components.")
+
+        lines.extend([
+            "",
+            "## Blockers & Discrepancies",
+        ])
+
+        active_contra = self._extract_active_contradictions(state)
+        if active_contra:
+            for c in active_contra:
+                lines.append(f"- BLOCKER [{c['severity']}]: {c['explanation']}")
+        else:
+            lines.append("- (none)")
+
+        lines.extend([
+            "",
+            "## Unverified Claims",
+        ])
+
+        if c_state.agent_claims:
+            for cl in c_state.agent_claims:
+                lines.append(f"- Claim: \"{cl.claim_text}\" (Agent:{cl.source_agent})")
+        else:
+            lines.append("- (none)")
+
+        return "\n".join(lines)