branchpy-cli 1.1.19__py3-none-any.whl

bqf/__init__.py

@@ -0,0 +1,16 @@
+"""
+BQF (BranchPy Quality Framework) - Policy-based validation system.
+
+This module provides the core infrastructure for BQF policy validation including:
+- Policy registry (YAML-based configuration)
+- Policy runner (dynamic validator loading and execution)
+- Event emission (lifecycle tracking)
+- Result aggregation (JSON formatting)
+
+Version: 0.9.1.1
+Created: 2025-11-12
+"""
+
+from .registry import PolicyRegistry, PolicyResult
+
+__all__ = ["PolicyRegistry", "PolicyResult"]

bqf/registry.py

@@ -0,0 +1,208 @@
+"""
+BQF Policy Registry - Dynamic policy loading and execution.
+
+This module provides the PolicyRegistry class for:
+- Loading policies from YAML configuration
+- Dynamically importing validator modules
+- Executing policies with event emission
+- Aggregating results into JSON format
+
+Version: 0.9.1.1
+Created: 2025-11-12
+"""
+
+import time
+from dataclasses import dataclass
+from importlib import import_module
+from pathlib import Path
+from typing import Literal, Optional
+
+import yaml
+
+
+@dataclass
+class PolicyResult:
+    """Result from a single policy validator execution."""
+
+    policy_id: str
+    status: Literal["pass", "warn", "fail"]
+    messages: list[str]
+    duration_ms: float
+    metadata: dict
+
+
+class PolicyRegistry:
+    """
+    BQF Policy Registry - manages policy loading and execution.
+
+    Usage:
+        registry = PolicyRegistry()
+        result = registry.run_policies("analyze", analysis_result, context)
+    """
+
+    def __init__(self, registry_path: Optional[Path] = None):
+        """
+        Initialize policy registry.
+
+        Args:
+            registry_path: Path to policies.yaml. If None, uses default location.
+        """
+        if registry_path is None:
+            registry_path = Path(__file__).parent / "policies.yaml"
+
+        self.registry_path = registry_path
+        self.policies = self._load_policies()
+
+    def _load_policies(self) -> list[dict]:
+        """Load policies from YAML configuration file."""
+        if not self.registry_path.exists():
+            raise FileNotFoundError(f"Policy registry not found: {self.registry_path}")
+
+        with open(self.registry_path, "r", encoding="utf-8") as f:
+            config = yaml.safe_load(f)
+
+        return config.get("policies", [])
+
+    def get_policies_for_module(
+        self, module: str, enabled_only: bool = True
+    ) -> list[dict]:
+        """
+        Get policies for a specific module.
+
+        Args:
+            module: Module name ("analyze", "compare", "media")
+            enabled_only: If True, only return enabled policies
+
+        Returns:
+            List of policy definitions for the module
+        """
+        policies = [p for p in self.policies if p["module"] == module]
+
+        if enabled_only:
+            policies = [p for p in policies if p.get("enabled", True)]
+
+        return policies
+
+    def _import_validator(self, validator_path: str):
+        """
+        Dynamically import validator function from module path.
+
+        Args:
+            validator_path: Dotted path like "bqf.validators.analyze.story_structure.validate"
+
+        Returns:
+            Validator function
+        """
+        module_path, func_name = validator_path.rsplit(".", 1)
+        validator_module = import_module(module_path)
+        return getattr(validator_module, func_name)
+
+    def run_policies(self, module: str, analysis_result: dict, context: dict) -> dict:
+        """
+        Run all enabled policies for a module.
+
+        Args:
+            module: Module name ("analyze", "compare", "media")
+            analysis_result: Full analysis/comparison/media result dict
+            context: Additional context (project_path, correlation_id, etc.)
+
+        Returns:
+            Aggregated BQF result dict with format:
+            {
+                "policies_run": 2,
+                "policies_passed": 2,
+                "policies_warned": 0,
+                "policies_failed": 0,
+                "duration_ms": 1.23,
+                "details": [...]  # Per-policy results
+            }
+        """
+        policies = self.get_policies_for_module(module, enabled_only=True)
+
+        if not policies:
+            return {
+                "policies_run": 0,
+                "policies_passed": 0,
+                "policies_warned": 0,
+                "policies_failed": 0,
+                "duration_ms": 0.0,
+                "details": [],
+            }
+
+        # Emit start event (TODO: integrate with governance.events)
+        correlation_id = context.get("correlation_id", "unknown")
+        self._emit_event(
+            "validation.policy.start",
+            {
+                "module": module,
+                "policy_count": len(policies),
+                "correlationId": correlation_id,
+            },
+        )
+
+        start_time = time.perf_counter()
+        results = []
+
+        for policy in policies:
+            try:
+                # Dynamically load validator
+                validator_func = self._import_validator(policy["validator"])
+
+                # Run validation
+                result = validator_func(analysis_result, context)
+                results.append(result)
+
+            except Exception as e:
+                # If validator fails to load or execute, treat as failure
+                results.append(
+                    PolicyResult(
+                        policy_id=policy["id"],
+                        status="fail",
+                        messages=[f"Validator error: {str(e)}"],
+                        duration_ms=0.0,
+                        metadata={"error": str(e)},
+                    )
+                )
+
+        total_duration_ms = (time.perf_counter() - start_time) * 1000
+
+        # Aggregate results (treat "info" as "warn" for counting)
+        aggregated = {
+            "policies_run": len(results),
+            "policies_passed": sum(1 for r in results if r.status == "pass"),
+            "policies_warned": sum(1 for r in results if r.status in ("warn", "info")),
+            "policies_failed": sum(1 for r in results if r.status == "fail"),
+            "duration_ms": round(total_duration_ms, 4),
+            "details": [
+                {
+                    "policy_id": r.policy_id,
+                    "status": r.status,
+                    "messages": r.messages,
+                    "duration_ms": round(r.duration_ms, 4),
+                    "metadata": r.metadata,
+                }
+                for r in results
+            ],
+        }
+
+        # Emit complete event
+        self._emit_event(
+            "validation.policy.complete",
+            {"module": module, "results": aggregated, "correlationId": correlation_id},
+        )
+
+        return aggregated
+
+    def _emit_event(self, event_name: str, data: dict):
+        """
+        Emit governance event (placeholder for future integration).
+
+        Args:
+            event_name: Event name following domain.action.phase pattern
+            data: Event data payload
+
+        TODO: Integrate with governance.events module in v0.9.2
+        """
+        # For now, just log to console (will integrate with governance logger later)
+        # print(f"[BQF EVENT] {event_name}: {data}")
+        pass  # Silent for now, will wire to governance.events in v0.9.2

branchpy/__init__.py

@@ -0,0 +1,29 @@
+from . import cli  # exposes branchpy.cli
+from . import parser, report
+from .contract import VERSION
+
+# Try to import telemetry and governance, but don't fail if they have optional dependencies
+try:
+    from . import telemetry
+except (ImportError, ModuleNotFoundError):
+    # telemetry has optional dependencies, skip if not available
+    pass
+
+try:
+    from . import governance
+except (ImportError, ModuleNotFoundError):
+    # governance may have optional dependencies, skip if not available
+    pass
+
+# Expose version as both VERSION and __version__ for compatibility
+__version__ = VERSION
+
+__all__ = [
+    "cli",
+    "parser",
+    "report",
+    "telemetry",
+    "governance",
+    "VERSION",
+    "__version__",
+]

branchpy/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main as cli_main
+
+if __name__ == "__main__":
+    raise SystemExit(cli_main())

branchpy/ai/__init__.py

@@ -0,0 +1,49 @@
+"""
+branchpy.ai.__init__.py
+BranchPy v1.0.0 — AI Integration Strategy
+
+AI-as-a-Service module for BranchPy.
+Supports multiple providers (OpenAI, Anthropic, Ollama, Venice.ai) with local API keys.
+
+Governance:
+- All AI operations emit governance events
+- Privacy-preserving: no data sent to BranchPy servers
+- User-controlled API keys
+
+Local AI Support:
+- Ollama provider for local Llama models (100% private)
+- LM Studio support (OpenAI-compatible)
+- Safe mode restricts to local-only providers
+
+BQS Compliance:
+- Input validation on all API calls
+- Rate limiting and error handling
+- Cross-platform compatibility
+"""
+
+from .ai_models import AIModel, AITask
+from .ai_routing import AIRouter
+from .config import AIConfig, ProviderConfig, load_ai_config
+from .protocol import AIProvider, ChatRequest, ChatResponse, Message, TokenUsage
+from .provider_manager import ProviderManager
+from .providers.ollama_provider import OllamaProvider
+from .providers.venice_provider import VeniceProvider
+
+__all__ = [
+    "ProviderManager",
+    "AIModel",
+    "AITask",
+    "AIRouter",
+    "AIProvider",
+    "ChatRequest",
+    "ChatResponse",
+    "Message",
+    "TokenUsage",
+    "ProviderConfig",
+    "AIConfig",
+    "load_ai_config",
+    "OllamaProvider",
+    "VeniceProvider",
+]
+
+__version__ = "1.0.0"

branchpy/ai/ai_models.py

@@ -0,0 +1,65 @@
+"""
+branchpy.ai.ai_models.py
+BranchPy v0.9.4 — AI Integration Strategy
+
+AI models and task definitions
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, Optional
+
+
+class AIModel(Enum):
+    """Supported AI models"""
+
+    GPT4 = "gpt-4"
+    GPT4_TURBO = "gpt-4-turbo"
+    GPT5 = "gpt-5"  # Future
+    CLAUDE_35_SONNET = "claude-3-5-sonnet-20241022"
+    CLAUDE_45 = "claude-4-5"  # Future
+
+
+class AITask(Enum):
+    """AI task types"""
+
+    CODE_REVIEW = "code_review"
+    DOCGEN = "documentation_generation"
+    SEMANTIC_ASSIST = "semantic_assistance"
+    ASSET_GUESS = "asset_guessing"
+    EXPLAIN_WARNING = "explain_warning"
+    HELP = "help_support"
+
+
+@dataclass
+class AIRequest:
+    """AI request data structure"""
+
+    task: AITask
+    provider: str
+    model: str
+    input_data: Dict[str, Any]
+    context: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class AIResponse:
+    """AI response data structure"""
+
+    task: AITask
+    provider: str
+    model: str
+    output: Any
+    metadata: Optional[Dict[str, Any]] = None
+    error: Optional[str] = None
+
+
+@dataclass
+class AIConfig:
+    """AI configuration"""
+
+    provider: str
+    api_key: str
+    model: Optional[str] = None
+    temperature: float = 0.5
+    max_tokens: int = 4096

branchpy/ai/ai_routing.py

@@ -0,0 +1,119 @@
+"""
+branchpy.ai.ai_routing.py
+BranchPy v0.9.4 — AI Integration Strategy
+
+AI task routing and execution
+Routes tasks to appropriate providers based on configuration and task type
+"""
+
+from typing import Any, Dict, Optional
+
+from .ai_models import AIRequest, AIResponse, AITask
+from .provider_manager import AIProvider, ProviderManager
+from .providers.anthropic_provider import AnthropicProvider
+from .providers.openai_provider import OpenAIProvider
+
+
+class AIRouter:
+    """
+    Routes AI tasks to appropriate providers.
+
+    Handles:
+    - Provider selection
+    - Task routing
+    - Error handling
+    - Governance event emission
+    """
+
+    def __init__(self):
+        self.provider_manager = ProviderManager()
+        self._providers: Dict[str, Any] = {}
+
+    def _get_provider_instance(self, provider: AIProvider):
+        """Get or create provider instance"""
+        if provider.value in self._providers:
+            return self._providers[provider.value]
+
+        api_key = self.provider_manager.get_api_key(provider)
+        if not api_key:
+            raise ValueError(f"No API key configured for {provider.value}")
+
+        model = self.provider_manager.get_model(provider)
+
+        if provider == AIProvider.OPENAI:
+            instance = OpenAIProvider(api_key, model or "gpt-4")
+        elif provider == AIProvider.ANTHROPIC:
+            instance = AnthropicProvider(api_key, model or "claude-3-5-sonnet-20241022")
+        else:
+            raise ValueError(f"Unsupported provider: {provider}")
+
+        self._providers[provider.value] = instance
+        return instance
+
+    def execute(self, request: AIRequest) -> AIResponse:
+        """
+        Execute an AI task.
+
+        Args:
+            request: AI request
+
+        Returns:
+            AI response
+        """
+        try:
+            # Get provider
+            provider = AIProvider(request.provider)
+            instance = self._get_provider_instance(provider)
+
+            # Route task
+            if request.task == AITask.CODE_REVIEW:
+                output = instance.code_review(
+                    code=request.input_data["code"],
+                    language=request.input_data.get("language", "python"),
+                )
+            elif request.task == AITask.DOCGEN:
+                output = instance.generate_documentation(
+                    code=request.input_data["code"],
+                    doc_type=request.input_data.get("doc_type", "readme"),
+                )
+            elif request.task == AITask.EXPLAIN_WARNING:
+                output = instance.explain_warning(
+                    warning_text=request.input_data["warning"],
+                    context=request.input_data.get("context"),
+                )
+            elif request.task == AITask.ASSET_GUESS:
+                if provider == AIProvider.ANTHROPIC:
+                    output = instance.guess_asset(
+                        asset_context=request.input_data["context"],
+                        available_assets=request.input_data["available_assets"],
+                    )
+                else:
+                    output = {"error": "Asset guessing only supported on Anthropic"}
+            else:
+                output = {"error": f"Unsupported task: {request.task}"}
+
+            return AIResponse(
+                task=request.task,
+                provider=request.provider,
+                model=request.model,
+                output=output,
+            )
+
+        except Exception as e:
+            return AIResponse(
+                task=request.task,
+                provider=request.provider,
+                model=request.model,
+                output=None,
+                error=str(e),
+            )
+
+    def is_available(self, provider: Optional[AIProvider] = None) -> bool:
+        """Check if AI is available"""
+        if provider is None:
+            provider = self.provider_manager.get_active_provider()
+
+        if provider is None:
+            return False
+
+        return self.provider_manager.is_configured(provider)

branchpy/ai/ai_tasks.py

@@ -0,0 +1,165 @@
+"""
+branchpy.ai.ai_tasks.py
+BranchPy v0.9.4 — AI Integration Strategy
+
+High-level AI task implementations
+Convenience functions for common AI operations
+"""
+
+from typing import Any, Dict, List, Optional
+
+from .ai_models import AIRequest, AITask
+from .ai_routing import AIRouter
+from .provider_manager import ProviderManager
+
+
+def code_review(
+    file_path: str, code: Optional[str] = None, language: str = "python"
+) -> Dict[str, Any]:
+    """
+    Run AI code review on a file.
+
+    Args:
+        file_path: Path to file
+        code: Optional code string (if not provided, read from file)
+        language: Programming language
+
+    Returns:
+        Review results
+    """
+    try:
+        if code is None:
+            with open(file_path, "r", encoding="utf-8") as f:
+                code = f.read()
+    except FileNotFoundError:
+        return {"error": f"File not found: {file_path}", "findings": []}
+    except Exception as e:
+        return {"error": f"Failed to read file: {str(e)}", "findings": []}
+
+    pm = ProviderManager()
+    provider = pm.get_active_provider()
+
+    if provider is None:
+        return {"error": "No AI provider configured", "findings": []}
+
+    model = pm.get_model(provider) or "default"
+
+    request = AIRequest(
+        task=AITask.CODE_REVIEW,
+        provider=provider.value,
+        model=model,
+        input_data={"code": code, "language": language},
+    )
+
+    router = AIRouter()
+    response = router.execute(request)
+
+    if response.error:
+        return {"error": response.error, "findings": []}
+
+    return response.output
+
+
+def generate_docs(code: str, doc_type: str = "readme") -> str:
+    """
+    Generate documentation for code.
+
+    Args:
+        code: Source code
+        doc_type: Documentation type
+
+    Returns:
+        Generated documentation
+    """
+    pm = ProviderManager()
+    provider = pm.get_active_provider()
+
+    if provider is None:
+        return "Error: No AI provider configured"
+
+    model = pm.get_model(provider) or "default"
+
+    request = AIRequest(
+        task=AITask.DOCGEN,
+        provider=provider.value,
+        model=model,
+        input_data={"code": code, "doc_type": doc_type},
+    )
+
+    router = AIRouter()
+    response = router.execute(request)
+
+    if response.error:
+        return f"Error: {response.error}"
+
+    return response.output
+
+
+def explain_warning(warning_text: str, context: Optional[str] = None) -> str:
+    """
+    Get AI explanation for a warning.
+
+    Args:
+        warning_text: Warning message
+        context: Optional context
+
+    Returns:
+        Explanation
+    """
+    pm = ProviderManager()
+    provider = pm.get_active_provider()
+
+    if provider is None:
+        return "Error: No AI provider configured"
+
+    model = pm.get_model(provider) or "default"
+
+    request = AIRequest(
+        task=AITask.EXPLAIN_WARNING,
+        provider=provider.value,
+        model=model,
+        input_data={"warning": warning_text, "context": context},
+    )
+
+    router = AIRouter()
+    response = router.execute(request)
+
+    if response.error:
+        return f"Error: {response.error}"
+
+    return response.output
+
+
+def guess_missing_asset(context: str, available_assets: List[str]) -> List[str]:
+    """
+    Guess missing asset based on context.
+
+    Args:
+        context: Asset context
+        available_assets: Available asset filenames
+
+    Returns:
+        List of suggestions
+    """
+    pm = ProviderManager()
+    provider = pm.get_active_provider()
+
+    if provider is None:
+        return []
+
+    model = pm.get_model(provider) or "default"
+
+    request = AIRequest(
+        task=AITask.ASSET_GUESS,
+        provider=provider.value,
+        model=model,
+        input_data={"context": context, "available_assets": available_assets},
+    )
+
+    router = AIRouter()
+    response = router.execute(request)
+
+    if response.error:
+        return []
+
+    return response.output if isinstance(response.output, list) else []

branchpy/ai/ast_integration/__init__.py

@@ -0,0 +1,28 @@
+"""AI integration with Python AST analysis.
+
+This module provides AI-powered code analysis using rich context
+extracted from Python AST nodes.
+
+Components:
+- ast_context: Extract rich context from AST for AI operations
+- code_review: AI-powered code review
+- explain_warning: AI explanations of BranchPy warnings
+- refactor: AI-powered refactoring suggestions
+"""
+
+from .ast_context import AIContext, ASTContextBuilder
+from .code_review import AICodeReviewer, CodeReview
+from .explain_warning import AIWarningExplainer, WarningExplanation
+from .refactor import AIRefactorSuggester, RefactoringPatch, RefactorSuggestion
+
+__all__ = [
+    "ASTContextBuilder",
+    "AIContext",
+    "AICodeReviewer",
+    "CodeReview",
+    "AIWarningExplainer",
+    "WarningExplanation",
+    "AIRefactorSuggester",
+    "RefactorSuggestion",
+    "RefactoringPatch",
+]