codrspot-processor-mcp 0.1.0__py3-none-any.whl

codepreproc_client/layer1_business/config.py

@@ -0,0 +1,104 @@
+"""Configuration loading helpers."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from contracts.dtos import LLMProviderConfig, Registry, Settings
+
+
+def apply_env_overrides(registry: Registry) -> Registry:
+    """Apply CODEPREPROC_* environment variables on top of a Registry loaded from PostgreSQL."""
+    d = registry.defaults
+    provider_data = {name: cfg.model_dump(mode="python") for name, cfg in d.llm_providers.items()}
+
+    if "CODEPREPROC_LLM_ENDPOINT" in os.environ or "CODEPREPROC_LLM_MODEL" in os.environ:
+        local = provider_data.get("local_qwen", {"type": "llamacpp"})
+        local["endpoint"] = os.getenv("CODEPREPROC_LLM_ENDPOINT", local.get("endpoint", d.llm_endpoint))
+        local["model"] = os.getenv("CODEPREPROC_LLM_MODEL", local.get("model", d.llm_model))
+        provider_data["local_qwen"] = local
+
+    if "CODEPREPROC_OPENAI_MODEL" in os.environ or "CODEPREPROC_OPENAI_API_KEY_ENV" in os.environ:
+        remote = provider_data.get(
+            "openai_4o_mini",
+            {"type": "openai", "model": "gpt-4o-mini", "api_key_env": "OPENAI_API_KEY"},
+        )
+        remote["model"] = os.getenv("CODEPREPROC_OPENAI_MODEL", remote.get("model", "gpt-4o-mini"))
+        remote["api_key_env"] = os.getenv(
+            "CODEPREPROC_OPENAI_API_KEY_ENV", remote.get("api_key_env", "OPENAI_API_KEY")
+        )
+        provider_data["openai_4o_mini"] = remote
+
+    new_defaults = d.model_copy(
+        update={
+            "embedding_model": os.getenv("CODEPREPROC_EMBEDDING_MODEL", d.embedding_model),
+            "reranker_model": os.getenv("CODEPREPROC_RERANKER_MODEL", d.reranker_model),
+            "llm_endpoint": os.getenv("CODEPREPROC_LLM_ENDPOINT", d.llm_endpoint),
+            "llm_model": os.getenv("CODEPREPROC_LLM_MODEL", d.llm_model),
+            "default_llm_policy": os.getenv("CODEPREPROC_DEFAULT_LLM_POLICY", d.default_llm_policy),
+            "llm_providers": {name: LLMProviderConfig.model_validate(item) for name, item in provider_data.items()},
+        }
+    )
+    return Registry(defaults=new_defaults, projects=registry.projects)
+
+
+def get_superkg_settings() -> tuple[bool, float]:
+    """Return (enabled, enrich_timeout_s) for SuperKG proxy calls through
+    codepreproc-server (POST /v1/superkg/*). The client never holds the real
+    SuperKG URL/credentials - only codepreproc-server does
+    (layer3_core/superkg/connector.py, server-side SUPERKG_URL)."""
+    enabled = _env_bool("SUPERKG_ENABLED", default=True)
+    enrich_timeout_ms = int(os.getenv("SUPERKG_ENRICH_TIMEOUT_MS") or "800")
+    return enabled, enrich_timeout_ms / 1000.0
+
+
+def _env_bool(name: str, default: bool = False) -> bool:
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _env_connection_verbosity(name: str, default: str = "basic") -> str:
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    value = raw.strip().lower()
+    if value in {"off", "basic", "verbose"}:
+        return value
+    return default
+
+
+def get_server_url() -> str:
+    """Base URL of the codepreproc-server API (contracts/openapi.yaml)."""
+
+    return os.getenv("CODEPREPROC_SERVER_URL", "https://localhost:8443")
+
+
+def get_credentials_path() -> Path:
+    """Path to credentials.yaml (the manifest), used only at mint time."""
+
+    return Path(os.getenv("CODEPREPROC_CREDENTIALS", str(get_home_dir() / "credentials.yaml")))
+
+
+def get_home_dir() -> Path:
+    """Return the codepreproc home directory."""
+
+    return Path(os.getenv("CODEPREPROC_HOME", Path.home() / ".codepreproc")).resolve()
+
+
+def get_settings() -> Settings:
+    """Build runtime settings."""
+
+    home_dir = get_home_dir()
+    indexes_dir = Path(os.getenv("CODEPREPROC_INDEXES_DIR", home_dir / "indexes")).resolve()
+    logs_dir = Path(os.getenv("CODEPREPROC_LOGS_DIR", home_dir / "logs")).resolve()
+
+    return Settings(
+        home_dir=home_dir,
+        indexes_dir=indexes_dir,
+        logs_dir=logs_dir,
+        debug=_env_bool("CODEPREPROC_DEBUG"),
+        mcp_connection_verbosity=_env_connection_verbosity("CODEPREPROC_MCP_CONNECTION_VERBOSITY"),
+    )

codepreproc_client/layer1_business/git_utils.py

@@ -0,0 +1,67 @@
+"""Git helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from git import InvalidGitRepositoryError, NoSuchPathError, Repo
+
+
+def get_repo_root(path: Path) -> Path | None:
+    """Return git root for a path, if any."""
+
+    try:
+        return Path(Repo(path, search_parent_directories=True).working_tree_dir or "").resolve()
+    except (InvalidGitRepositoryError, NoSuchPathError):
+        return None
+
+
+def get_current_sha(repo: Repo) -> str:
+    """Return HEAD SHA."""
+
+    return repo.head.commit.hexsha
+
+
+def get_current_branch(repo: Repo) -> str:
+    """Return current branch name or detached marker."""
+
+    try:
+        return repo.active_branch.name
+    except TypeError:
+        return "DETACHED"
+
+
+def get_remote_url(repo: Repo) -> str | None:
+    """Return origin URL if available."""
+
+    try:
+        return next(iter(repo.remotes)).url
+    except (StopIteration, AttributeError):
+        return None
+
+
+def get_dirty_files(repo: Repo) -> list[Path]:
+    """Return modified and untracked files relative to repo root."""
+
+    root = Path(repo.working_tree_dir or ".").resolve()
+    dirty = {root / item.a_path for item in repo.index.diff(None)}
+    dirty.update(root / path for path in repo.untracked_files)
+    return sorted(path.resolve() for path in dirty if path.exists() and path.is_file())
+
+
+def diff_files_between_sha(repo: Repo, old_sha: str, new_sha: str) -> list[Path]:
+    """Return changed files between two SHAs."""
+
+    root = Path(repo.working_tree_dir or ".").resolve()
+    diff_items = repo.commit(old_sha).diff(new_sha)
+    files = {root / item.a_path for item in diff_items if item.a_path}
+    files.update(root / item.b_path for item in diff_items if item.b_path)
+    return sorted(path.resolve() for path in files if path.exists() and path.is_file())
+
+
+def normalize_content(text: str) -> str:
+    """Normalize line endings and BOM for consistent hashing."""
+
+    if text.startswith("\ufeff"):
+        text = text.removeprefix("\ufeff")
+    return text.replace("\r\n", "\n").replace("\r", "\n")

codepreproc_client/layer1_business/license/fingerprint.py

@@ -0,0 +1,61 @@
+"""Derive a project fingerprint from git identity (architecture doc S8).
+
+Fingerprints repo *identity*, not *state*. Two methods:
+
+- `project_lock_commit` (robust, recommended for regulated verticals):
+  hash of the committed `.codepreproc/project.lock` id. Mutates the repo,
+  but survives rebase/squash/filter-repo since it's just tracked content.
+- `early_history_sample` (non-invasive): hash of the repo's earliest
+  commit SHAs. Doesn't mutate the repo, but is fragile to history rewrite
+  and shallow clones.
+
+The local check here is a speed-bump against *accident*; the real gate is
+the server re-deriving and comparing at promote time
+(layer1_authority/fingerprint_registry.py) - this module never asserts
+its own output is trustworthy.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+from git import Repo
+
+from contracts.dtos import FingerprintAttestation
+from codepreproc_client.layer1_business.license.project_lock import read_project_lock
+
+EARLY_HISTORY_SAMPLE_SIZE = 5
+
+
+def _hash(*parts: str) -> str:
+    return hashlib.sha256("|".join(parts).encode("utf-8")).hexdigest()
+
+
+def _sample_early_commit_shas(repo: Repo) -> list[str]:
+    commits = list(repo.iter_commits(reverse=True))
+    return [c.hexsha for c in commits[:EARLY_HISTORY_SAMPLE_SIZE]]
+
+
+def derive_fingerprint(project_id: str, repo_root: Path) -> FingerprintAttestation:
+    """Derive a `FingerprintAttestation` for `repo_root`, preferring the robust method."""
+
+    repo = Repo(repo_root)
+
+    lock_id = read_project_lock(repo_root)
+    if lock_id:
+        return FingerprintAttestation(
+            project_id=project_id,
+            fingerprint_hash=_hash("project_lock", lock_id),
+            method="project_lock_commit",
+        )
+
+    sampled_shas = _sample_early_commit_shas(repo)
+    if not sampled_shas:
+        raise RuntimeError(f"cannot_derive_fingerprint_no_commits: {repo_root}")
+    return FingerprintAttestation(
+        project_id=project_id,
+        fingerprint_hash=_hash("early_history", *sampled_shas),
+        method="early_history_sample",
+        sampled_commit_shas=sampled_shas,
+    )

codepreproc_client/layer1_business/license/jwt_client.py

@@ -0,0 +1,60 @@
+"""Obtain/refresh the 1h JWT lease and attach it as a bearer token (architecture doc S6).
+
+`credentials.yaml` is read once, at mint time. The JWT itself is the
+offline lease: the client can keep operating up to 1h without re-minting,
+so a network blip shorter than that survives transparently.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+import httpx
+
+from contracts.dtos import FingerprintAttestation, Manifest
+
+DEFAULT_TIMEOUT_S = 15.0
+# Refresh a little before actual expiry so an in-flight call never races the deadline.
+REFRESH_SKEW_S = 30.0
+
+
+class MintRefusedError(RuntimeError):
+    """Raised when the server refuses to mint (seat/project quota exceeded, invalid manifest)."""
+
+
+class JWTClient:
+    """Caches the current JWT and transparently re-mints it once it's near expiry."""
+
+    def __init__(self, *, base_url: str, manifest: Manifest, fingerprint_attestation: FingerprintAttestation) -> None:
+        self._base_url = base_url
+        self._manifest = manifest
+        self._fingerprint_attestation = fingerprint_attestation
+        self._jwt: str | None = None
+        self._expires_at: datetime | None = None
+
+    async def get_bearer_token(self) -> str:
+        """Return a valid JWT, minting or refreshing it first if necessary."""
+
+        if self._jwt is None or self._is_near_expiry():
+            await self._mint()
+        return self._jwt  # type: ignore[return-value]
+
+    def _is_near_expiry(self) -> bool:
+        if self._expires_at is None:
+            return True
+        remaining = (self._expires_at - datetime.now(timezone.utc)).total_seconds()
+        return remaining <= REFRESH_SKEW_S
+
+    async def _mint(self) -> None:
+        request_body = {
+            "manifest": self._manifest.model_dump(mode="json"),
+            "fingerprint_attestation": self._fingerprint_attestation.model_dump(mode="json"),
+        }
+        async with httpx.AsyncClient(base_url=self._base_url, timeout=DEFAULT_TIMEOUT_S) as client:
+            response = await client.post("/v1/mint", json=request_body)
+            if response.status_code == 403:
+                raise MintRefusedError(response.json().get("message", "mint_refused"))
+            response.raise_for_status()
+            body = response.json()
+            self._jwt = body["jwt"]
+            self._expires_at = datetime.fromisoformat(body["expires_at"])

codepreproc_client/layer1_business/license/project_lock.py

@@ -0,0 +1,44 @@
+"""Read/write .codepreproc/project.lock (architecture doc S8, robust method).
+
+Injects a legitimate tooling artifact into the client's repo (a small
+committed file whose hash the server controls the meaning of) so project
+identity survives history rewrites. This mutates the client's repo, which
+is why it's opt-in per the "robust" vs "non-invasive" fingerprint choice
+in fingerprint.py.
+"""
+
+from __future__ import annotations
+
+import uuid
+from pathlib import Path
+
+LOCK_RELATIVE_PATH = Path(".codepreproc") / "project.lock"
+
+
+def read_project_lock(repo_root: Path) -> str | None:
+    """Return the lock id in `<repo_root>/.codepreproc/project.lock`, or None if absent."""
+
+    lock_path = repo_root / LOCK_RELATIVE_PATH
+    if not lock_path.is_file():
+        return None
+    content = lock_path.read_text(encoding="utf-8").strip()
+    return content or None
+
+
+def write_project_lock(repo_root: Path, lock_id: str | None = None) -> str:
+    """Write a new project.lock file (if one doesn't already exist) and return its lock id.
+
+    Does not commit the file - the caller is expected to `git add` and
+    commit it as part of onboarding, so its presence in history is what
+    makes the "robust" fingerprint method robust.
+    """
+
+    existing = read_project_lock(repo_root)
+    if existing:
+        return existing
+
+    lock_path = repo_root / LOCK_RELATIVE_PATH
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    new_lock_id = lock_id or uuid.uuid4().hex
+    lock_path.write_text(new_lock_id + "\n", encoding="utf-8")
+    return new_lock_id

codepreproc_client/layer1_business/local_registry.py

@@ -0,0 +1,40 @@
+"""Local, on-disk mirror of registered projects.
+
+register_project() (api_client/registry_client.py) is the source of truth
+for licensing/quota purposes, but list_projects/project_status must not need
+a network round trip merely to enumerate what's registered on this machine -
+this module caches the last-known ProjectConfig per project_id, refreshed
+every time register_project() succeeds.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from contracts.dtos import ProjectConfig
+
+_FILENAME = "projects.json"
+
+
+def _registry_path(home_dir: Path) -> Path:
+    return home_dir / _FILENAME
+
+
+def load_local_projects(home_dir: Path) -> dict[str, ProjectConfig]:
+    path = _registry_path(home_dir)
+    if not path.exists():
+        return {}
+    raw = json.loads(path.read_text(encoding="utf-8"))
+    return {project_id: ProjectConfig.model_validate(data) for project_id, data in raw.items()}
+
+
+def save_local_project(home_dir: Path, project: ProjectConfig) -> None:
+    projects = load_local_projects(home_dir)
+    projects[project.project_id] = project
+    path = _registry_path(home_dir)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps({pid: p.model_dump(mode="json") for pid, p in projects.items()}, indent=2),
+        encoding="utf-8",
+    )

codepreproc_client/layer1_business/manifest/credentials.py

@@ -0,0 +1,35 @@
+"""Parse and validate credentials.yaml into a Manifest (architecture doc S6).
+
+Used only at mint time - `Minter` on the server, `mint()` client-side
+below - never sent per call.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from contracts.dtos import Manifest
+
+
+class CredentialsError(RuntimeError):
+    """Raised when credentials.yaml is missing or malformed."""
+
+
+def load_manifest(path: str | Path) -> Manifest:
+    """Load and validate a credentials.yaml file into a `Manifest`."""
+
+    credentials_path = Path(path)
+    if not credentials_path.is_file():
+        raise CredentialsError(f"credentials_file_not_found: {credentials_path}")
+
+    try:
+        raw = yaml.safe_load(credentials_path.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError as exc:
+        raise CredentialsError(f"credentials_yaml_invalid: {exc}") from exc
+
+    try:
+        return Manifest.model_validate(raw)
+    except Exception as exc:
+        raise CredentialsError(f"credentials_schema_invalid: {exc}") from exc

codepreproc_client/layer1_business/mcp/action_monitor.py

@@ -0,0 +1,246 @@
+"""MCP action progress and timeout monitoring."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class ToolExecutionError(RuntimeError):
+    """Structured execution error for MCP tools."""
+
+    def __init__(self, code: str, message: str, *, details: dict[str, Any] | None = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.details = details or {}
+
+    def to_payload(self, *, tool: str, stage: str | None = None) -> dict[str, Any]:
+        payload = {
+            "error": self.code,
+            "message": self.message,
+            "details": {
+                "tool": tool,
+                **self.details,
+            },
+        }
+        if stage is not None:
+            payload["details"]["stage"] = stage
+        return payload
+
+
+class ActionInactivityTimeout(ToolExecutionError):
+    """Raised when an MCP action stops making relevant progress."""
+
+    def __init__(
+        self,
+        *,
+        tool: str,
+        stage: str,
+        idle_seconds: int,
+        timeout_seconds: int,
+        last_progress: dict[str, Any],
+    ) -> None:
+        super().__init__(
+            "action_timed_out",
+            f"Action exceeded {timeout_seconds}s without relevant progress in stage '{stage}'.",
+            details={
+                "tool": tool,
+                "stage": stage,
+                "idle_seconds": idle_seconds,
+                "timeout_seconds": timeout_seconds,
+                "last_progress": last_progress,
+            },
+        )
+
+
+@dataclass
+class ActionMonitor:
+    """Emit MCP progress/log notifications and enforce inactivity timeouts."""
+
+    session: Any
+    logger: logging.Logger
+    tool: str
+    request_id: str | int
+    timeout_seconds: int
+    heartbeat_seconds: int
+    progress_token: str | int | None = None
+    project: str | None = None
+    stage_name: str = "queued"
+    progress_value: float = 0.0
+    total: float | None = None
+    started_at: float = field(default_factory=time.monotonic)
+    last_relevant_change_at: float = field(default_factory=time.monotonic)
+    last_progress: dict[str, Any] = field(default_factory=dict)
+    _closed: bool = False
+    _timeout_error: ActionInactivityTimeout | None = None
+    _heartbeat_task: asyncio.Task[None] | None = None
+    _owner_task: asyncio.Task[Any] | None = None
+
+    async def start(self, message: str, *, project: str | None = None) -> None:
+        self.project = project or self.project
+        self._owner_task = asyncio.current_task()
+        await self._emit(
+            event="started",
+            stage="started",
+            message=message,
+            relevant=True,
+        )
+        self._heartbeat_task = asyncio.create_task(self._heartbeat_loop())
+
+    async def complete(self, message: str, *, details: dict[str, Any] | None = None) -> None:
+        await self._emit(
+            event="completed",
+            stage=self.stage_name,
+            message=message,
+            relevant=True,
+            details=details,
+        )
+        await self.close()
+
+    async def fail(self, message: str, *, stage: str | None = None, details: dict[str, Any] | None = None) -> None:
+        await self._emit(
+            event="failed",
+            stage=stage or self.stage_name,
+            message=message,
+            relevant=False,
+            details=details,
+            level="error",
+        )
+        await self.close()
+
+    async def stage(
+        self,
+        stage: str,
+        message: str,
+        *,
+        relevant: bool = True,
+        details: dict[str, Any] | None = None,
+        progress_increment: float = 1.0,
+        total: float | None = None,
+    ) -> None:
+        await self._emit(
+            event="progress",
+            stage=stage,
+            message=message,
+            relevant=relevant,
+            details=details,
+            progress_increment=progress_increment,
+            total=total,
+        )
+
+    async def check_active(self) -> None:
+        if self._timeout_error is not None:
+            raise self._timeout_error
+
+    async def close(self) -> None:
+        self._closed = True
+        if self._heartbeat_task is not None:
+            self._heartbeat_task.cancel()
+            try:
+                await self._heartbeat_task
+            except asyncio.CancelledError:
+                pass
+            self._heartbeat_task = None
+
+    def timeout_error(self) -> ActionInactivityTimeout | None:
+        return self._timeout_error
+
+    async def _heartbeat_loop(self) -> None:
+        try:
+            while not self._closed:
+                await asyncio.sleep(self.heartbeat_seconds)
+                if self._closed:
+                    return
+                idle_seconds = int(time.monotonic() - self.last_relevant_change_at)
+                if idle_seconds >= self.timeout_seconds:
+                    self._timeout_error = ActionInactivityTimeout(
+                        tool=self.tool,
+                        stage=self.stage_name,
+                        idle_seconds=idle_seconds,
+                        timeout_seconds=self.timeout_seconds,
+                        last_progress=dict(self.last_progress),
+                    )
+                    if self._owner_task is not None:
+                        self._owner_task.cancel()
+                    return
+                elapsed_seconds = int(time.monotonic() - self.started_at)
+                await self._emit(
+                    event="heartbeat",
+                    stage=self.stage_name,
+                    message=f"{self.tool}: sigo en {self.stage_name} ({elapsed_seconds}s transcurridos, {idle_seconds}s sin avance relevante)",
+                    relevant=False,
+                    details={
+                        "elapsed_seconds": elapsed_seconds,
+                        "idle_seconds": idle_seconds,
+                    },
+                )
+        except asyncio.CancelledError:
+            raise
+
+    async def _emit(
+        self,
+        *,
+        event: str,
+        stage: str,
+        message: str,
+        relevant: bool,
+        details: dict[str, Any] | None = None,
+        progress_increment: float = 1.0,
+        total: float | None = None,
+        level: str = "info",
+    ) -> None:
+        self.stage_name = stage
+        merged_details = {
+            "tool": self.tool,
+            "stage": stage,
+            "event": event,
+            "project": self.project,
+            **(details or {}),
+        }
+        if relevant:
+            self.progress_value += progress_increment
+            self.last_relevant_change_at = time.monotonic()
+            self.last_progress = {
+                "stage": stage,
+                "message": message,
+                "progress": self.progress_value,
+                **merged_details,
+            }
+        if total is not None:
+            self.total = total
+        self.logger.log(
+            logging.ERROR if level == "error" else logging.INFO,
+            "mcp_action tool=%s event=%s stage=%s project=%s progress=%s details=%s message=%s",
+            self.tool,
+            event,
+            stage,
+            self.project,
+            self.progress_value,
+            merged_details,
+            message,
+        )
+        if self.session is not None:
+            try:
+                await self.session.send_log_message(
+                    level=level,
+                    data=message,
+                    logger="codepreproc.mcp",
+                    related_request_id=self.request_id,
+                )
+            except Exception:
+                self.logger.debug("failed_to_send_log_message tool=%s stage=%s", self.tool, stage, exc_info=True)
+            if self.progress_token is not None:
+                try:
+                    await self.session.send_progress_notification(
+                        progress_token=self.progress_token,
+                        progress=self.progress_value,
+                        total=self.total,
+                        message=message,
+                        related_request_id=self.request_id,
+                    )
+                except Exception:
+                    self.logger.debug("failed_to_send_progress tool=%s stage=%s", self.tool, stage, exc_info=True)