vcase-auto-context 0.1.0__py3-none-any.whl

vcase/__init__.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import os
+import httpx
+
+from vcase.api.pypi_client import PypiClient
+from vcase.api.npm_client import NpmClient
+from vcase.service.api_index_cache import ApiIndexCache
+from vcase.providers.python_provider import PythonProvider
+from vcase.providers.node_provider import NodeProvider
+from vcase.service.detector import TechnologyDetector
+from vcase.service.resolver import DependencyResolver
+from vcase.service.retriever import DocumentationRetriever
+from vcase.service.spec_builder import SpecBuilder
+from vcase.service.api_validator import ApiValidator
+from vcase.service.architecture_validator import ArchitectureValidator
+from vcase.service.llm_validator import LlmValidator
+from vcase.service.orchestrator import Orchestrator
+
+
+def create_orchestrator(
+    http_client: httpx.AsyncClient,
+    model_name: str | None = None,
+    api_key: str | None = None,
+    provider: str | None = None,
+) -> Orchestrator:
+    """Helper factory function to construct a fully configured Orchestrator pipeline."""
+    pypi_client = PypiClient(http_client)
+    npm_client = NpmClient(http_client)
+    cache = ApiIndexCache(http_client)
+
+    python_prov = PythonProvider(pypi_client, cache)
+    node_prov = NodeProvider(npm_client)
+
+    detector = TechnologyDetector([python_prov, node_prov])
+    resolver = DependencyResolver([python_prov, node_prov])
+    retriever = DocumentationRetriever([python_prov, node_prov])
+    
+    spec_builder = SpecBuilder()
+    api_validator = ApiValidator()
+    arch_validator = ArchitectureValidator()
+    
+    llm_validator = LlmValidator(
+        model_name=model_name,
+        api_key=api_key,
+        provider=provider
+    )
+
+    return Orchestrator(
+        detector=detector,
+        resolver=resolver,
+        retriever=retriever,
+        spec_builder=spec_builder,
+        api_validator=api_validator,
+        architecture_validator=arch_validator,
+        llm_validator=llm_validator,
+        model_name=model_name,
+        api_key=api_key,
+        provider=provider
+    )

vcase/api/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

vcase/api/github_client.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import logging
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+GITHUB_API_BASE_URL = "https://api.github.com"
+REQUEST_TIMEOUT_SECONDS = 10
+
+
+class GithubClient:
+
+    def __init__(self, client: httpx.AsyncClient, api_token: str | None = None) -> None:
+        ...
+
+    async def get_release_notes(self, owner: str, repo: str, tag: str) -> str:
+        """Return release notes markdown for a given tag."""
+        ...
+
+    async def get_readme(self, owner: str, repo: str, ref: str) -> str:
+        """Return the README content for a given ref (tag or branch)."""
+        ...

vcase/api/npm_client.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import logging
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+NPM_REGISTRY_BASE_URL = "https://registry.npmjs.org"
+REQUEST_TIMEOUT_SECONDS = 10
+
+
+class NpmClient:
+
+    def __init__(self, client: httpx.AsyncClient) -> None:
+        self._client = client
+
+    async def get_package_info(self, package: str, version: str) -> dict:
+        """Fetch package metadata from npm registry. Raises on non-200 response."""
+        url = f"{NPM_REGISTRY_BASE_URL}/{package}/{version}"
+        response = await self._client.get(url, timeout=REQUEST_TIMEOUT_SECONDS)
+        response.raise_for_status()
+        return response.json()
+
+    async def get_latest_version(self, package: str) -> str:
+        """Return the latest published version string for a package."""
+        url = f"{NPM_REGISTRY_BASE_URL}/{package}"
+        response = await self._client.get(url, timeout=REQUEST_TIMEOUT_SECONDS)
+        response.raise_for_status()
+        data = response.json()
+        version = data.get("dist-tags", {}).get("latest", "")
+        if not version:
+            logger.warning("Could not determine latest version for npm package %s", package)
+        return version

vcase/api/pypi_client.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import logging
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+PYPI_BASE_URL = "https://pypi.org/pypi"
+REQUEST_TIMEOUT_SECONDS = 10
+
+
+class PypiClient:
+
+    def __init__(self, client: httpx.AsyncClient) -> None:
+        self._client=client
+
+    async def get_package_info(self, package: str, version: str) -> dict:
+        """Fetch package metadata from PyPI. Raises on non-200 response."""
+        url=f"{PYPI_BASE_URL}/{package}/{version}/json"
+        response=await self._client.get(url,timeout=REQUEST_TIMEOUT_SECONDS)
+        response.raise_for_status()
+        return response.json()
+
+
+    async def get_latest_version(self, package: str) -> str:
+        """Return the latest published version string for a package."""
+        url=f"{PYPI_BASE_URL}/{package}/json"
+        response=await self._client.get(url,timeout=REQUEST_TIMEOUT_SECONDS)
+        response.raise_for_status()
+        data=response.json()
+        version= data.get("info",{}).get("version","")
+        if not version:
+            logger.warning("Could not determine latest version for %s",package)
+        return version
+

vcase/api/web_scraper.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import logging
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+REQUEST_TIMEOUT_SECONDS = 15
+
+
+class WebScraper:
+
+    def __init__(self, client: httpx.AsyncClient) -> None:
+        ...
+
+    async def fetch_as_markdown(self, url: str) -> str:
+        """
+        Fetch a URL and return its content as clean markdown.
+        Strips navigation, ads, and irrelevant HTML. Raises on failure.
+        """
+        ...
+
+    def _html_to_markdown(self, html: str) -> str:
+        ...

vcase/cli.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+from pathlib import Path
+import httpx
+import uvicorn
+from dotenv import load_dotenv
+
+from vcase import create_orchestrator
+
+
+def main() -> None:
+    # Load environment variables
+    load_dotenv(override=True)
+    parser = argparse.ArgumentParser(
+        description="Version-Constrained API Specification Engine (VCASE)"
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # serve command
+    serve_parser = subparsers.add_parser("serve", help="Start the VCASE FastAPI server")
+    serve_parser.add_argument("--host", default="127.0.0.1", help="Host binding address")
+    serve_parser.add_argument("--port", type=int, default=8000, help="Port to listen on")
+    serve_parser.add_argument("--reload", action="store_true", help="Enable hot reloading")
+
+    # run command
+    run_parser = subparsers.add_parser("run", help="Generate and validate code directly from the CLI")
+    run_parser.add_argument("--prompt", required=True, help="User instructions / prompt")
+    run_parser.add_argument("--repo-path", required=True, help="Path to local repository to inspect stack/versions")
+    run_parser.add_argument("--target-file", help="Optional relative path to target file to generate/edit")
+    run_parser.add_argument("--api-key", help="API key for the selected LLM provider")
+    run_parser.add_argument("--model", help="Model name to use for generation and validation")
+    run_parser.add_argument("--provider", choices=["openai", "gemini", "openrouter", "groq"], help="LLM API provider")
+
+    # context command
+    context_parser = subparsers.add_parser("context", help="Retrieve versioned specification context for code generation")
+    context_parser.add_argument("--prompt", required=True, help="User prompt or instructions")
+    context_parser.add_argument("--repo-path", required=True, help="Path to local repository to inspect stack/versions")
+
+    # validate command
+    validate_parser = subparsers.add_parser("validate", help="Validate/lint code against dependency contracts and rules")
+    validate_parser.add_argument("--code-file", required=True, help="Path to Python file containing code to validate")
+    validate_parser.add_argument("--repo-path", required=True, help="Path to local repository")
+
+    args = parser.parse_args()
+
+    if args.command == "serve":
+        print(f"Starting VCASE API proxy server on http://{args.host}:{args.port}...")
+        # Since uvicorn.run expects target app, we pass the package module target path
+        uvicorn.run("vcase.main:app", host=args.host, port=args.port, reload=args.reload)
+        
+    elif args.command == "run":
+        repo_path = Path(args.repo_path)
+        if not repo_path.exists():
+            print(f"Error: Repository path '{args.repo_path}' does not exist.", file=sys.stderr)
+            sys.exit(1)
+
+        async def run_pipeline():
+            async with httpx.AsyncClient() as http_client:
+                orchestrator = create_orchestrator(
+                    http_client,
+                    model_name=args.model,
+                    api_key=args.api_key,
+                    provider=args.provider
+                )
+                try:
+                    # Execute orchestrator pipeline
+                    target_file = Path(args.target_file) if args.target_file else None
+                    code = await orchestrator.run(args.prompt, repo_path, target_file=target_file)
+                    print("\n--- GENERATED & VALIDATED CODE ---")
+                    print(code)
+                    print("----------------------------------\n")
+                    print("Status: Validation Passed.")
+                    
+                    if target_file:
+                        target_file_path = repo_path / target_file if not target_file.is_absolute() else target_file
+                        # Ensure directories exist
+                        target_file_path.parent.mkdir(parents=True, exist_ok=True)
+                        target_file_path.write_text(code, encoding="utf-8")
+                        print(f"Saved generated code directly to: {target_file_path}")
+                except ValueError as e:
+                    print(f"\nValidation Failed:\n{e}", file=sys.stderr)
+                    sys.exit(2)
+                except Exception as e:
+                    print(f"\nOrchestrator Execution Failed:\n{e}", file=sys.stderr)
+                    sys.exit(3)
+
+        asyncio.run(run_pipeline())
+
+    elif args.command == "context":
+        repo_path = Path(args.repo_path)
+        if not repo_path.exists():
+            print(f"Error: Repository path '{args.repo_path}' does not exist.", file=sys.stderr)
+            sys.exit(1)
+
+        async def get_context():
+            async with httpx.AsyncClient() as http_client:
+                orchestrator = create_orchestrator(http_client)
+                try:
+                    techs = orchestrator._detector.detect_technologies_in_prompt(args.prompt)
+                    resolved_deps = await orchestrator._resolver.resolve(repo_path)
+                    for dep in resolved_deps:
+                        if dep.name not in techs:
+                            techs.append(dep.name)
+
+                    api_indexes = []
+                    for dep in resolved_deps:
+                        idx = await orchestrator._retriever.retrieve(dep)
+                        if idx:
+                            api_indexes.append(idx)
+
+                    # Scan workspace
+                    from vcase.service.workspace_scanner import WorkspaceScanner
+                    scanner = WorkspaceScanner()
+                    workspace_idx, _ = scanner.scan(repo_path)
+                    if workspace_idx and workspace_idx.signatures:
+                        api_indexes.append(workspace_idx)
+
+                    from vcase.service.interaction_graph import get_active_patterns
+                    patterns = get_active_patterns(techs)
+
+                    context_prompt = orchestrator._spec_builder.build_system_prompt(
+                        api_indexes, patterns, user_prompt=args.prompt
+                    )
+                    print(context_prompt)
+                except Exception as e:
+                    print(f"Error gathering context: {e}", file=sys.stderr)
+                    sys.exit(1)
+
+        asyncio.run(get_context())
+
+    elif args.command == "validate":
+        repo_path = Path(args.repo_path)
+        code_file = Path(args.code_file)
+        if not repo_path.exists():
+            print(f"Error: Repository path '{args.repo_path}' does not exist.", file=sys.stderr)
+            sys.exit(1)
+        if not code_file.exists():
+            print(f"Error: Code file '{args.code_file}' does not exist.", file=sys.stderr)
+            sys.exit(1)
+
+        async def run_validation():
+            async with httpx.AsyncClient() as http_client:
+                orchestrator = create_orchestrator(http_client)
+                try:
+                    code = code_file.read_text(encoding="utf-8")
+                    resolved_deps = await orchestrator._resolver.resolve(repo_path)
+                    techs = [dep.name for dep in resolved_deps]
+
+                    api_indexes = []
+                    for dep in resolved_deps:
+                        idx = await orchestrator._retriever.retrieve(dep)
+                        if idx:
+                            api_indexes.append(idx)
+
+                    # Scan workspace
+                    from vcase.service.workspace_scanner import WorkspaceScanner
+                    scanner = WorkspaceScanner()
+                    workspace_idx, local_modules = scanner.scan(repo_path)
+                    if workspace_idx and workspace_idx.signatures:
+                        api_indexes.append(workspace_idx)
+
+                    from vcase.service.interaction_graph import get_constraints_for, get_active_patterns
+                    patterns = get_active_patterns(techs)
+                    constraints = []
+                    for tech in techs:
+                        constraints.extend(get_constraints_for(tech))
+
+                    api_res = orchestrator._api_validator.validate(
+                        code, api_indexes, extra_whitelisted_imports=local_modules
+                    )
+                    arch_res = orchestrator._architecture_validator.validate(
+                        code, patterns, constraints
+                    )
+
+                    violations = api_res.violations + arch_res.violations
+                    errors = [v for v in violations if v.severity == "error"]
+                    warnings = [v for v in violations if v.severity == "warning"]
+
+                    if violations:
+                        print(f"Validation failed with {len(errors)} errors and {len(warnings)} warnings:", file=sys.stderr)
+                        for v in violations:
+                            print(f"- [{v.severity.upper()}] [{v.rule_name}]: {v.description}", file=sys.stderr)
+                        sys.exit(2)
+                    else:
+                        print("Validation passed successfully! No contract violations found.")
+                except Exception as e:
+                    print(f"Error running validation: {e}", file=sys.stderr)
+                    sys.exit(3)
+
+        asyncio.run(run_validation())
+
+
+if __name__ == "__main__":
+    main()

vcase/main.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import logging
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv(override=True)
+
+from fastapi import FastAPI
+
+from vcase.routers import health, proxy
+
+app = FastAPI(
+    title="Runtime Knowledge Streaming API",
+    version="0.1.0",
+    docs_url="/docs",
+    redoc_url="/redoc",
+)
+
+app.include_router(health.router)
+app.include_router(proxy.router)

vcase/providers/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

vcase/providers/base.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+
+
+class ResolutionTier(int, Enum):
+    LOCK_FILE = 1
+    DECLARATION = 2
+    CONTAINERIZED = 3
+
+
+class Ecosystem(str, Enum):
+    PYTHON = "python"
+    NODE = "node"
+    RUST = "rust"
+    JAVA = "java"
+    GO = "go"
+    RUBY = "ruby"
+
+
+class SourceReliability(int, Enum):
+    OFFICIAL_DOCS = 4
+    GITHUB_RELEASE = 3
+    PACKAGE_REGISTRY = 2
+    COMMUNITY = 1
+
+
+@dataclass(frozen=True)
+class RawDependency:
+    name: str
+    version_constraint: str
+    ecosystem: Ecosystem
+
+
+@dataclass(frozen=True)
+class ResolvedDependency:
+    name: str
+    version: str
+    ecosystem: Ecosystem
+    resolution_tier: ResolutionTier
+
+
+@dataclass(frozen=True)
+class DocSource:
+    url: str
+    reliability: SourceReliability
+    package: str
+    version: str
+
+
+@dataclass(frozen=True)
+class ApiParameter:
+    name: str
+    type_hint: str
+    required: bool
+    description: str
+
+
+@dataclass(frozen=True)
+class ApiSignature:
+    qualified_name: str
+    parameters: tuple[ApiParameter, ...]
+    return_type: str
+    available_since: str
+    deprecated: bool = False
+    deprecation_note: str = ""
+
+
+@dataclass(frozen=True)
+class ApiIndex:
+    package: str
+    version: str
+    signatures: tuple[ApiSignature, ...]
+
+
+@dataclass(frozen=True)
+class InteractionConstraint:
+    rule_name: str
+    allowed_in: tuple[str, ...]
+    disallowed_in: tuple[str, ...]
+    description: str
+
+
+@dataclass(frozen=True)
+class TechnologyPattern:
+    technologies: tuple[str, ...]
+    description: str
+    correct_pattern: str
+    incorrect_pattern: str
+    constraint: InteractionConstraint
+
+
+@dataclass
+class ValidationViolation:
+    rule_name: str
+    description: str
+    line_number: int | None
+    severity: str
+
+
+@dataclass
+class ValidationResult:
+    passed: bool
+    violations: list[ValidationViolation] = field(default_factory=list)
+
+
+class EcosystemProvider(ABC):
+
+    @abstractmethod
+    def detect(self, repo_path: Path) -> bool:
+        """Return True if this provider applies to the repository at repo_path."""
+
+    @abstractmethod
+    def parse_dependencies(self, repo_path: Path) -> list[RawDependency]:
+        """Extract dependency names and version constraints from manifest files."""
+
+    @abstractmethod
+    async def resolve_versions(self, deps: list[RawDependency]) -> list[ResolvedDependency]:
+        """Resolve exact compatible versions using registry APIs."""
+
+    @abstractmethod
+    async def documentation_sources(self, package: str, version: str) -> list[DocSource]:
+        """Return ranked documentation source URLs for the given package version."""
+
+    @abstractmethod
+    async def api_index(self, package: str, version: str) -> ApiIndex:
+        """Return structured API signatures and parameters for the given package version."""
+
+