prompt-capability-optimizer 1.0.0

package/prompt_capability_optimizer/engine.py

@@ -0,0 +1,201 @@
+# Copyright (c) 2026 Mahmoud Abdelhameid (Develper.net@gmail.com). All rights reserved.
+# Licensed under the MIT License.
+
+"""
+Prompt Capability Optimizer Core Engine
+=======================================
+End-to-end execution pipeline connecting classification, capability graph,
+discovery, trust evaluation, two-pass optimization, self-critique, and Mode C lifecycle.
+"""
+
+from typing import Dict, Any, List, Optional
+from .models import PromptIR, Resource, ClassificationReport, CritiqueReport, RiskLevel
+from .config import DEFAULT_CONFIG, OptimizerConfig
+from .classification.task_classifier import TaskClassifier
+from .intent.intent_analyzer import IntentAnalyzer
+from .capabilities.extractor import CapabilityExtractor
+from .capabilities.graph import CapabilityGraph
+from .discovery.registry import ResourceRegistry
+from .discovery.local_discovery import LocalSkillDiscovery
+from .discovery.mcp_discovery import McpDiscovery
+from .discovery.web_discovery import WebDiscovery
+from .discovery.find_skills_adapter import FindSkillsAdapter
+from .security.trust_engine import TrustEngine
+from .security.injection_detector import PromptInjectionDetector
+from .security.secret_protector import SecretProtector
+from .scoring.deduplicator import CapabilityDeduplicator
+from .verification.verification_engine import VerificationEngine
+from .optimization.optimizer import TwoPassOptimizer
+from .critique.self_critique_engine import SelfCritiqueEngine
+
+class PromptOptimizerEngine:
+    
+    def __init__(self, config: Optional[OptimizerConfig] = None):
+        self.config = config or DEFAULT_CONFIG
+        self.registry = ResourceRegistry()
+        self.find_skills_adapter = FindSkillsAdapter()
+        self.web_discovery = WebDiscovery()
+        
+    def _populate_discovery(self, required_caps: List[str], depth: int):
+        # 1. Real local skill discovery
+        local_skills = LocalSkillDiscovery.discover()
+        self.registry.register_many(local_skills)
+        
+        # 2. Real host MCP discovery with parsed state machine
+        mcp_servers = McpDiscovery.discover()
+        self.registry.register_many(mcp_servers)
+        
+        # 3. Real find-skills integration: query for specialized capabilities
+        if depth >= 1 and self.config.enable_find_skills_cli:
+            for cap_name in required_caps:
+                # Query open skills ecosystem for packages matching capability
+                skills_results = self.find_skills_adapter.search(cap_name, limit=2)
+                if skills_results:
+                    self.registry.register_many(skills_results)
+                    
+        # 4. Real Web Discovery pipeline for dynamic/unseen technologies
+        if depth >= 1 and self.config.enable_web_discovery:
+            for cap_name in required_caps:
+                web_docs = self.web_discovery.discover_for_capability(cap_name)
+                if web_docs:
+                    self.registry.register_many(web_docs)
+                
+    def optimize(self, raw_prompt: str, mode: str = "B", confirmed_execution: bool = False) -> Dict[str, Any]:
+        """
+        Executes the full pipeline:
+        Intent -> Classify -> Capabilities -> Discovery -> Scoring -> Two-Pass Optimization -> Critique -> Mode C Governance -> Output
+        """
+        # Step 0: Security Sanity Check (Secret protection & Prompt Injection Detection)
+        secrets_found = SecretProtector.find_secrets(raw_prompt)
+        safe_prompt = SecretProtector.redact(raw_prompt)
+        injection_scan = PromptInjectionDetector.scan(safe_prompt)
+        if injection_scan["is_suspicious"]:
+            safe_prompt = PromptInjectionDetector.sanitize(safe_prompt)
+
+        # Step 1: Classification & Intent
+        classification = TaskClassifier.classify(safe_prompt)
+        intent_data = IntentAnalyzer.analyze(safe_prompt)
+        
+        # Step 2: Capability Extraction & Graph
+        caps = CapabilityExtractor.extract_capabilities(safe_prompt)
+        cap_graph = CapabilityGraph(caps)
+        required_cap_names = cap_graph.get_capability_names()
+        
+        # Step 3: Real Discovery (Local, find-skills, MCP, Web)
+        self.registry.clear()
+        self._populate_discovery(required_cap_names, classification.level)
+        
+        # Step 4: Capability Matching & Trust Evaluation
+        matched_resources: List[Resource] = []
+        for cap_name in required_cap_names:
+            found = self.registry.find_by_capability(cap_name)
+            for r in found:
+                TrustEngine.evaluate_resource_trust(r)
+                if r not in matched_resources:
+                    matched_resources.append(r)
+                    
+        # Step 5: Scoring, Filtering & Deduplication
+        max_skills = self.config.max_skills_level_4 if classification.level >= 4 else self.config.max_skills_per_prompt
+        selected_resources = CapabilityDeduplicator.deduplicate(
+            matched_resources,
+            max_count=max_skills,
+            min_utility=self.config.utility_conditional_threshold
+        )
+        
+        # Ensure at least baseline agent execution tool is bound for complex tasks if none was discovered
+        if not selected_resources and classification.level >= 2:
+            selected_resources.append(Resource(
+                id="builtin:native-agent-tools",
+                name="Native Host Agent Execution Tools",
+                type=ResourceType.BUILTIN_TOOL,
+                source="host_runtime",
+                capabilities=["filesystem-access", "shell-execution"],
+                relevance=8.0,
+                capability_match=8.0,
+                quality=9.0,
+                trust=10.0,
+                reputation=10.0,
+                compatibility=10.0,
+                freshness=10.0,
+                overhead=1.0,
+                risk=0.0,
+                risk_level=RiskLevel.NO_SIDE_EFFECT
+            ))
+        
+        # Step 6: Dynamic Repository Verification
+        verification_directives = VerificationEngine.derive_verification_directives()
+        
+        # Step 7: Two-Pass Optimization
+        prompt_ir = TwoPassOptimizer.optimize(
+            raw_prompt=safe_prompt,
+            classification=classification,
+            selected_resources=selected_resources,
+            verification_cmds=verification_directives
+        )
+        rendered_prompt = TwoPassOptimizer.render_prompt(prompt_ir)
+        
+        # Step 8: Real Qualitative Self-Critique
+        critique_report = SelfCritiqueEngine.evaluate(rendered_prompt, depth=classification.level)
+        
+        # Step 9: Automatic Correction Pass (if critique indicates missing requirements)
+        if not critique_report.passed:
+            for rec in critique_report.recommendations:
+                if "negative" in rec.lower():
+                    prompt_ir.negative_constraints.append("Do NOT alter unrequested codebase layers.")
+                if "completion" in rec.lower():
+                    prompt_ir.completion_criteria.append("100% of integration checks pass against baseline.")
+            rendered_prompt = TwoPassOptimizer.render_prompt(prompt_ir)
+            # Re-evaluate
+            critique_report = SelfCritiqueEngine.evaluate(rendered_prompt, depth=classification.level)
+            
+        # Step 10: Mode C Lifecycle & Governance Check
+        execution_status = "NOT_REQUESTED"
+        if mode.upper() == "C":
+            task_has_side_effects = any(kw in safe_prompt.lower() for kw in ["install", "deploy", "delete", "drop", "publish", "push", "remove", "migrate"])
+            resource_has_side_effects = any(r.risk_level in [RiskLevel.EXTERNAL_SIDE_EFFECT, RiskLevel.DESTRUCTIVE] for r in selected_resources)
+            has_side_effects = task_has_side_effects or resource_has_side_effects
+            
+            if has_side_effects and not confirmed_execution:
+                execution_status = "AWAITING_USER_APPROVAL (Side-effects detected; explicit confirmation required)"
+            else:
+                execution_status = "READY_FOR_CONTROLLED_EXECUTION"
+
+        return {
+            "mode": mode.upper(),
+            "execution_status": execution_status,
+            "classification": {
+                "level": classification.level,
+                "confidence": classification.confidence,
+                "signals": classification.signals,
+                "reasoning": classification.reasoning
+            },
+            "required_capabilities": required_cap_names,
+            "selected_resources": [
+                {
+                    "name": r.name,
+                    "type": r.type.value,
+                    "utility_score": r.utility_score,
+                    "trust": r.trust,
+                    "source": r.source,
+                    "risk_level": r.risk_level.value
+                }
+                for r in selected_resources
+            ],
+            "security": {
+                "secrets_redacted": len(secrets_found),
+                "injection_threats_neutralized": len(injection_scan["threats_detected"])
+            },
+            "critique": {
+                "passed": critique_report.passed,
+                "score": critique_report.score,
+                "confidence": critique_report.confidence,
+                "critical_issues": critique_report.critical_issues,
+                "recommendations": critique_report.recommendations
+            },
+            "diff": {
+                "added_constraints": prompt_ir.diff.added_constraints,
+                "selected_capabilities": prompt_ir.diff.selected_capabilities,
+                "verification_directives": prompt_ir.diff.added_verification
+            },
+            "optimized_prompt": rendered_prompt
+        }

package/prompt_capability_optimizer/intent/__init__.py

@@ -0,0 +1,6 @@
+# Copyright (c) 2026 Mahmoud Abdelhameid (Develper.net@gmail.com). All rights reserved.
+# Licensed under the MIT License.
+
+from .intent_analyzer import IntentAnalyzer
+
+__all__ = ["IntentAnalyzer"]

package/prompt_capability_optimizer/intent/intent_analyzer.py

@@ -0,0 +1,61 @@
+# Copyright (c) 2026 Mahmoud Abdelhameid (Develper.net@gmail.com). All rights reserved.
+# Licensed under the MIT License.
+
+"""
+Semantic Intent Analyzer
+========================
+Dissects user prompts into primary intent, explicit constraints, input expectations,
+and required deliverables while guarding against intent alteration.
+"""
+
+import re
+from typing import Dict, Any, List
+
+class IntentAnalyzer:
+    
+    ACTION_VERBS = [
+        "build", "create", "implement", "design", "refactor", "fix",
+        "debug", "audit", "optimize", "test", "explain", "review", "migrate"
+    ]
+    
+    @classmethod
+    def analyze(cls, raw_prompt: str) -> Dict[str, Any]:
+        cleaned = raw_prompt.strip()
+        lines = [line.strip() for line in cleaned.splitlines() if line.strip()]
+        
+        primary_intent = lines[0] if lines else cleaned
+        action_verb = "execute"
+        for v in cls.ACTION_VERBS:
+            if re.search(rf"\b{v}\b", primary_intent, re.IGNORECASE):
+                action_verb = v.lower()
+                break
+                
+        # Detect explicit user constraints (e.g., using ..., with ..., do not ...)
+        constraints = []
+        negative_constraints = []
+        
+        # Look for negative directives
+        neg_matches = re.findall(r"\b(?:do not|don't|never|without|avoid)\s+([^,.;\n]+)", cleaned, re.IGNORECASE)
+        for nm in neg_matches:
+            negative_constraints.append(f"Do not {nm.strip()}")
+            
+        # Look for explicit technology or pattern constraints
+        tech_matches = re.findall(r"\b(?:using|with|in)\s+([A-Za-z0-9_\-\+\#\.\s]+?)(?:,|\.|\n|and|$)", cleaned, re.IGNORECASE)
+        for tm in tech_matches:
+            item = tm.strip()
+            if len(item) > 1 and item.lower() not in ["the", "a", "an", "this", "these"]:
+                constraints.append(f"Utilize {item}")
+
+        # Formulate a crisp objective sentence
+        objective = primary_intent
+        if not objective.endswith("."):
+            objective += "."
+            
+        return {
+            "primary_intent": primary_intent,
+            "action_verb": action_verb,
+            "objective": objective,
+            "explicit_constraints": constraints,
+            "negative_constraints": negative_constraints,
+            "raw_text": cleaned
+        }

package/prompt_capability_optimizer/models.py

@@ -0,0 +1,162 @@
+# Copyright (c) 2026 Mahmoud Abdelhameid (Develper.net@gmail.com). All rights reserved.
+# Licensed under the MIT License.
+
+"""
+Core Data Models and Normalized Schemas
+=======================================
+Defines common dataclasses for capabilities, discovered resources, host runtime
+specifications, prompt intermediate representations, and critique results.
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Dict, Any, Optional, Set
+from enum import Enum
+
+class ResourceType(str, Enum):
+    SKILL = "skill"
+    MCP = "mcp"
+    CONNECTOR = "connector"
+    PLUGIN = "plugin"
+    BUILTIN_TOOL = "tool"
+    WEB_RESOURCE = "web_resource"
+    DOCUMENTATION = "documentation"
+
+class CapabilityStatus(str, Enum):
+    AVAILABLE = "available"
+    UNAVAILABLE = "unavailable"
+    UNKNOWN = "unknown"
+    HOST_DECLARED = "host_declared"
+    RUNTIME_DETECTED = "runtime_detected"
+    INFERRED = "inferred"
+
+class McpServerStatus(str, Enum):
+    CONFIGURED = "CONFIGURED"
+    PARSED = "PARSED"
+    REACHABLE = "REACHABLE"
+    INITIALIZED = "INITIALIZED"
+    TOOLS_DISCOVERED = "TOOLS_DISCOVERED"
+
+class RiskLevel(str, Enum):
+    NO_SIDE_EFFECT = "NO_SIDE_EFFECT"
+    LOW_RISK = "LOW_RISK"
+    EXTERNAL_SIDE_EFFECT = "EXTERNAL_SIDE_EFFECT"
+    DESTRUCTIVE = "DESTRUCTIVE"
+
+class RequirementCategory(str, Enum):
+    USER_EXPLICIT = "USER_EXPLICIT"
+    DERIVED_NECESSITY = "DERIVED_NECESSITY"
+    PROJECT_CONSTRAINT = "PROJECT_CONSTRAINT"
+    SECURITY_REQUIREMENT = "SECURITY_REQUIREMENT"
+    VERIFICATION_REQUIREMENT = "VERIFICATION_REQUIREMENT"
+    OPTIONAL_RECOMMENDATION = "OPTIONAL_RECOMMENDATION"
+
+@dataclass
+class ClassifiedRequirement:
+    text: str
+    category: RequirementCategory
+    source: str = "intent"
+
+@dataclass
+class Capability:
+    name: str
+    domain: str = "general"
+    importance: float = 1.0  # 0.0 - 1.0
+    dependencies: List[str] = field(default_factory=list)
+    description: str = ""
+
+@dataclass
+class Resource:
+    id: str
+    name: str
+    type: ResourceType
+    source: str  # local, registry, host, web
+    capabilities: List[str] = field(default_factory=list)
+    location: Optional[str] = None
+    relevance: float = 5.0          # 0.0 - 10.0
+    capability_match: float = 5.0   # 0.0 - 10.0
+    quality: float = 5.0            # 0.0 - 10.0
+    trust: float = 5.0              # 0.0 - 10.0 (security/integrity)
+    reputation: float = 5.0         # 0.0 - 10.0 (stars/downloads/community)
+    compatibility: float = 8.0      # 0.0 - 10.0
+    freshness: float = 5.0          # 0.0 - 10.0
+    overhead: float = 2.0           # 0.0 - 10.0
+    risk: float = 1.0               # 0.0 - 10.0
+    risk_level: RiskLevel = RiskLevel.LOW_RISK
+    permissions: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    
+    @property
+    def utility_score(self) -> float:
+        """
+        Authoritative formula from references/scoring_rubric.md:
+        Utility = (0.25*R + 0.25*M + 0.15*Q + 0.15*T + 0.10*C + 0.05*F) - (0.10*O + 0.20*K)
+        """
+        pos = (
+            0.25 * self.relevance +
+            0.25 * self.capability_match +
+            0.15 * self.quality +
+            0.15 * self.trust +
+            0.10 * self.compatibility +
+            0.05 * self.freshness
+        )
+        neg = (0.10 * self.overhead) + (0.20 * self.risk)
+        return round(pos - neg, 3)
+
+@dataclass
+class HostCapabilityItem:
+    capability: str
+    status: CapabilityStatus
+    confidence: float
+    details: Dict[str, Any] = field(default_factory=dict)
+
+@dataclass
+class ClassificationReport:
+    level: int  # 0 to 4
+    confidence: float
+    signals: List[str]
+    reasoning: str
+
+@dataclass
+class CritiqueFinding:
+    dimension: str
+    passed: bool
+    score: float
+    finding: str
+    recommendation: str
+
+@dataclass
+class CritiqueReport:
+    passed: bool
+    score: float
+    confidence: float
+    findings: List[CritiqueFinding]
+    critical_issues: List[str] = field(default_factory=list)
+    recommendations: List[str] = field(default_factory=list)
+
+@dataclass
+class PromptDiff:
+    removed_ambiguities: List[str] = field(default_factory=list)
+    added_constraints: List[str] = field(default_factory=list)
+    added_verification: List[str] = field(default_factory=list)
+    selected_capabilities: List[str] = field(default_factory=list)
+    preserved_intent_summary: str = ""
+
+@dataclass
+class PromptIR:
+    raw_prompt: str
+    role: str = ""
+    objective: str = ""
+    context: str = ""
+    categorized_requirements: List[ClassifiedRequirement] = field(default_factory=list)
+    constraints: List[str] = field(default_factory=list)
+    negative_constraints: List[str] = field(default_factory=list)
+    optional_recommendations: List[str] = field(default_factory=list)
+    required_capabilities: List[str] = field(default_factory=list)
+    selected_resources: List[Resource] = field(default_factory=list)
+    implementation_requirements: List[str] = field(default_factory=list)
+    edge_cases: List[str] = field(default_factory=list)
+    verification_directives: List[str] = field(default_factory=list)
+    completion_criteria: List[str] = field(default_factory=list)
+    phased_execution: List[Dict[str, Any]] = field(default_factory=list)
+    diff: PromptDiff = field(default_factory=PromptDiff)
+    depth: int = 1

package/prompt_capability_optimizer/optimization/__init__.py

@@ -0,0 +1,8 @@
+# Copyright (c) 2026 Mahmoud Abdelhameid (Develper.net@gmail.com). All rights reserved.
+# Licensed under the MIT License.
+
+from .semantic_pass import SemanticPass
+from .execution_pass import ExecutionPass
+from .optimizer import TwoPassOptimizer
+
+__all__ = ["SemanticPass", "ExecutionPass", "TwoPassOptimizer"]

package/prompt_capability_optimizer/optimization/execution_pass.py

@@ -0,0 +1,52 @@
+# Copyright (c) 2026 Mahmoud Abdelhameid (Develper.net@gmail.com). All rights reserved.
+# Licensed under the MIT License.
+
+"""
+Pass 2 — Execution Optimization
+===============================
+Binds selected capabilities, discovered tools, phased execution milestones,
+and repository-aware verification directives.
+"""
+
+from typing import List, Dict, Any
+from ..models import PromptIR, Resource
+
+class ExecutionPass:
+    
+    @classmethod
+    def execute(cls, prompt_ir: PromptIR, selected_resources: List[Resource], verification_cmds: List[str]) -> PromptIR:
+        prompt_ir.selected_resources = selected_resources
+        prompt_ir.diff.selected_capabilities = [r.name for r in selected_resources]
+        
+        # 1. Bind Verification Commands
+        prompt_ir.verification_directives = verification_cmds
+        prompt_ir.diff.added_verification = verification_cmds
+        
+        # 2. Build Phased Milestones (for Level >= 2)
+        if prompt_ir.depth >= 2:
+            prompt_ir.phased_execution = [
+                {
+                    "phase": 1,
+                    "title": "Baseline Inspection",
+                    "goal": "Verify existing tests and repository conventions prior to modification."
+                },
+                {
+                    "phase": 2,
+                    "title": "Contract & Schema Definition",
+                    "goal": "Establish immutable interfaces, DTOs, and validation boundaries."
+                },
+                {
+                    "phase": 3,
+                    "title": "Core Implementation",
+                    "goal": "Implement business logic following additive change standards."
+                },
+                {
+                    "phase": 4,
+                    "title": "Verification & Static Analysis",
+                    "goal": "Run typechecking, unit/e2e tests, and regression verification."
+                }
+            ]
+        else:
+            prompt_ir.phased_execution = []
+            
+        return prompt_ir

package/prompt_capability_optimizer/optimization/optimizer.py

@@ -0,0 +1,85 @@
+# Copyright (c) 2026 Mahmoud Abdelhameid (Develper.net@gmail.com). All rights reserved.
+# Licensed under the MIT License.
+
+"""
+Two-Pass Optimizer Orchestrator
+===============================
+Coordinates semantic and execution passes, formats final structured prompts,
+and renders concise prompt diffs.
+"""
+
+from typing import List, Dict, Any
+from ..models import PromptIR, Resource, ClassificationReport
+from .semantic_pass import SemanticPass
+from .execution_pass import ExecutionPass
+
+class TwoPassOptimizer:
+    
+    @classmethod
+    def optimize(
+        cls,
+        raw_prompt: str,
+        classification: ClassificationReport,
+        selected_resources: List[Resource],
+        verification_cmds: List[str]
+    ) -> PromptIR:
+        # Initialize PromptIR
+        prompt_ir = PromptIR(
+            raw_prompt=raw_prompt,
+            objective=raw_prompt.strip(),
+            depth=classification.level
+        )
+        
+        # Pass 1: Semantic Clarification
+        prompt_ir = SemanticPass.execute(prompt_ir, classification)
+        
+        # Pass 2: Execution Binding
+        prompt_ir = ExecutionPass.execute(prompt_ir, selected_resources, verification_cmds)
+        
+        return prompt_ir
+
+    @classmethod
+    def render_prompt(cls, ir: PromptIR) -> str:
+        """
+        Renders PromptIR into canonical prompt format.
+        """
+        lines = []
+        lines.append(f"ROLE:\n{ir.role}\n")
+        lines.append(f"OBJECTIVE:\n{ir.objective}\n")
+        
+        if ir.context:
+            lines.append(f"CONTEXT & REPO STATE:\n{ir.context}\n")
+            
+        if ir.constraints or ir.negative_constraints:
+            lines.append("CONSTRAINTS & NON-NEGOTIABLES:")
+            for c in ir.constraints:
+                lines.append(f"- {c}")
+            for nc in ir.negative_constraints:
+                lines.append(f"- {nc}")
+            lines.append("")
+            
+        if ir.selected_resources:
+            lines.append("REQUIRED CAPABILITIES & TOOLS:")
+            for r in ir.selected_resources:
+                lines.append(f"- {r.name} ({r.type.value} from {r.source})")
+            lines.append("")
+            
+        if ir.phased_execution:
+            lines.append("PHASED EXECUTION PLAN:")
+            for p in ir.phased_execution:
+                lines.append(f"Phase {p['phase']} — {p['title']}: {p['goal']}")
+            lines.append("")
+            
+        if ir.verification_directives:
+            lines.append("VERIFICATION & TESTING DIRECTIVES:")
+            for v in ir.verification_directives:
+                lines.append(f"- {v}")
+            lines.append("")
+            
+        if ir.completion_criteria:
+            lines.append("COMPLETION CRITERIA:")
+            for cc in ir.completion_criteria:
+                lines.append(f"- {cc}")
+            lines.append("")
+            
+        return "\n".join(lines).strip()