medcheck 0.1.0__py3-none-any.whl

medcheck/__init__.py

@@ -0,0 +1,3 @@
+"""MedCheck - AI-powered medical imaging analysis toolkit."""
+
+__version__ = "0.1.0"

medcheck/core/__init__.py

@@ -0,0 +1 @@
+"""Core functionality for MedCheck."""

medcheck/core/config.py

@@ -0,0 +1,28 @@
+"""Application configuration via environment variables."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Settings:
+    host: str = field(default_factory=lambda: os.environ.get("MEDCHECK_HOST", "0.0.0.0"))  # nosec B104
+    port: int = field(default_factory=lambda: int(os.environ.get("MEDCHECK_PORT", "8080")))
+    default_llm_provider: str = field(default_factory=lambda: os.environ.get("MEDCHECK_LLM_PROVIDER", "claude"))
+    default_language: str = field(default_factory=lambda: os.environ.get("MEDCHECK_LANGUAGE", "en"))
+    anthropic_api_key: str | None = field(default_factory=lambda: os.environ.get("ANTHROPIC_API_KEY"))
+    openai_api_key: str | None = field(default_factory=lambda: os.environ.get("OPENAI_API_KEY"))
+    google_api_key: str | None = field(default_factory=lambda: os.environ.get("GOOGLE_API_KEY"))
+
+    def available_llm_providers(self) -> list[str]:
+        providers: list[str] = []
+        if self.anthropic_api_key:
+            providers.append("claude")
+        if self.openai_api_key:
+            providers.append("openai")
+        if self.google_api_key:
+            providers.append("gemini")
+        providers.append("local")
+        return providers

medcheck/core/context.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class PatientInfo:
+    name: str = ""
+    patient_id: str = ""
+    birth_date: str = ""
+    sex: str = ""
+    age: str = ""
+
+
+@dataclass
+class StudyInfo:
+    date: str = ""
+    description: str = ""
+    institution: str = ""
+    manufacturer: str = ""
+    model_name: str = ""
+    field_strength: str = ""
+
+
+@dataclass
+class DicomSeries:
+    description: str = ""
+    plane: str = ""
+    modality: str = ""
+    series_number: int = 0
+    slices: list[Any] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SignalStats:
+    mean_intensity: list[float] = field(default_factory=list)
+    max_intensity: list[float] = field(default_factory=list)
+    high_signal_ratio: list[float] = field(default_factory=list)
+    high_signal_slices: list[int] = field(default_factory=list)
+
+
+@dataclass
+class StructureFinding:
+    name: str = ""
+    status: str = ""
+    findings: str = ""
+    confidence: float = 0.0
+    slices_evaluated: int = 0
+    secondary_signs: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ClinicalContext:
+    symptoms: str = ""
+    trauma: str = ""
+    trauma_date: str = ""
+    suspected_diagnosis: str = ""
+    patient_age: int = 0
+    patient_sex: str = ""
+    anatomy: str = ""
+
+
+@dataclass
+class PipelineContext:
+    dicom_series: list[DicomSeries] = field(default_factory=list)
+    patient: PatientInfo = field(default_factory=PatientInfo)
+    # Ingest config
+    source: str = ""
+    provider_name: str = "local"
+    credentials: dict[str, str] = field(default_factory=dict)
+    study: StudyInfo = field(default_factory=StudyInfo)
+    volumes: dict[str, Any] = field(default_factory=dict)
+    detected_anatomy: str | None = None
+    detected_planes: dict[str, Any] = field(default_factory=dict)
+    clinical_context: ClinicalContext | None = None
+    anomaly_scores: dict[str, Any] = field(default_factory=dict)
+    top_slices: dict[str, Any] = field(default_factory=dict)
+    signal_analysis: dict[str, Any] = field(default_factory=dict)
+    annotated_images: dict[str, Any] = field(default_factory=dict)
+    findings: list[StructureFinding] = field(default_factory=list)
+    overall_impression: str = ""
+    clinical_correlation: str = ""
+    limitations: list[str] = field(default_factory=list)
+    report_path: str = ""
+    report_format: str = "json"
+    report_language: str = "en"
+    output_dir: str = ""
+    step_config: dict[str, Any] = field(default_factory=dict)

medcheck/core/step.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from medcheck.core.context import PipelineContext
+
+
+class PipelineStep(ABC):
+    name: str = ""
+
+    @abstractmethod
+    def run(self, context: PipelineContext) -> PipelineContext:
+        """Execute this step and return the (modified) context."""
+
+    def validate(self, context: PipelineContext) -> bool:
+        """Validate preconditions before running. Returns True by default."""
+        return True

medcheck/core/workflow.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from typing import Any
+
+import yaml
+from rich.console import Console
+
+from medcheck.core.context import PipelineContext
+from medcheck.core.step import PipelineStep
+
+console = Console()
+
+
+class StepRegistry:
+    """Registry that maps step names to PipelineStep subclasses."""
+
+    def __init__(self) -> None:
+        self._steps: dict[str, type[PipelineStep]] = {}
+
+    def register(self, name: str, step_class: type[PipelineStep]) -> None:
+        """Register a step class under the given name."""
+        self._steps[name] = step_class
+
+    def get(self, name: str) -> type[PipelineStep]:
+        """Return the step class for *name*, raising KeyError if not found."""
+        if name not in self._steps:
+            raise KeyError(name)
+        return self._steps[name]
+
+    def list_steps(self) -> list[str]:
+        """Return registered step names in insertion order."""
+        return list(self._steps.keys())
+
+
+class WorkflowEngine:
+    """Orchestrates sequential execution of pipeline steps."""
+
+    def __init__(self, registry: StepRegistry) -> None:
+        self.registry = registry
+
+    def run(
+        self,
+        steps: list[str],
+        context: PipelineContext,
+        step_configs: dict[str, Any] | None = None,
+    ) -> PipelineContext:
+        """Instantiate and run each step in *steps* order.
+
+        Args:
+            steps: Ordered list of step names to execute.
+            context: The shared pipeline context passed through all steps.
+            step_configs: Optional per-step configuration dicts keyed by name.
+
+        Returns:
+            The (potentially mutated) context after all steps have run.
+
+        Raises:
+            KeyError: If a step name is not found in the registry.
+        """
+        step_configs = step_configs or {}
+
+        for name in steps:
+            step_class = self.registry.get(name)  # raises KeyError if unknown
+            step_instance = step_class()
+            console.print(f"[bold blue]▶ Running step:[/bold blue] {name}")
+            if not step_instance.validate(context):
+                console.print(f"[yellow]Skipping {name}: prerequisites not met[/yellow]")
+                continue
+            context.step_config = step_configs.get(name, {})
+            context = step_instance.run(context)
+            console.print(f"[bold green]✔ Completed step:[/bold green] {name}")
+
+        return context
+
+    def run_from_yaml(
+        self,
+        yaml_path: str,
+        context: PipelineContext,
+    ) -> PipelineContext:
+        """Load a workflow YAML file and run its steps.
+
+        Expected YAML format::
+
+            name: my_workflow
+            steps:
+              - step_name:          # value may be null or a config dict
+              - another_step:
+                  param: value
+
+        Args:
+            yaml_path: Path to the YAML workflow definition file.
+            context: The shared pipeline context.
+
+        Returns:
+            The context after all steps have run.
+        """
+        with open(yaml_path, encoding="utf-8") as fh:
+            workflow_def = yaml.safe_load(fh)
+
+        raw_steps: list[Any] = workflow_def.get("steps", [])
+
+        step_names: list[str] = []
+        step_configs: dict[str, Any] = {}
+
+        for entry in raw_steps:
+            if isinstance(entry, str):
+                step_names.append(entry)
+            elif isinstance(entry, dict):
+                for step_name, cfg in entry.items():
+                    step_names.append(step_name)
+                    if cfg is not None:
+                        step_configs[step_name] = cfg
+
+        workflow_name = workflow_def.get("name", yaml_path)
+        console.print(f"[bold cyan]Workflow:[/bold cyan] {workflow_name}")
+
+        return self.run(steps=step_names, context=context, step_configs=step_configs)

medcheck/llm/__init__.py

@@ -0,0 +1 @@
+"""LLM client and interaction utilities."""

medcheck/llm/base.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+from medcheck.core.context import ClinicalContext, StructureFinding
+
+
+@dataclass
+class AnnotatedImage:
+    series_name: str
+    slice_index: int
+    image_bytes: bytes
+    description: str
+
+
+@dataclass
+class AnalysisResult:
+    overall_impression: str = ""
+    raw_response: str = ""
+    structures: list[StructureFinding] = field(default_factory=list)
+    clinical_correlation: str = ""
+    limitations: list[str] = field(default_factory=list)
+
+
+def parse_llm_json(raw: str) -> dict[str, Any]:
+    """Extract and parse the first valid JSON object from *raw* using brace-depth tracking."""
+    start = raw.index("{")
+    depth = 0
+    for i, ch in enumerate(raw[start:], start):
+        if ch == "{":
+            depth += 1
+        elif ch == "}":
+            depth -= 1
+        if depth == 0:
+            result: dict[str, Any] = json.loads(raw[start : i + 1])
+            return result
+    raise ValueError("No valid JSON found")
+
+
+def parse_llm_response(raw: str) -> AnalysisResult:
+    """Shared response parser used by all LLM providers."""
+    try:
+        data = parse_llm_json(raw)
+        structures = [StructureFinding(**s) for s in data.get("structures", [])]
+        return AnalysisResult(
+            structures=structures,
+            overall_impression=data.get("overall_impression", ""),
+            clinical_correlation=data.get("clinical_correlation", ""),
+            limitations=data.get("limitations", []),
+            raw_response=raw,
+        )
+    except (ValueError, json.JSONDecodeError, TypeError):
+        return AnalysisResult(overall_impression=raw, raw_response=raw)
+
+
+class LLMProvider(ABC):
+    name: str = ""
+    supports_vision: bool = False
+
+    @abstractmethod
+    def check_available(self) -> bool:
+        """Return True if this provider is configured and reachable."""
+
+    @abstractmethod
+    def analyze_images(
+        self,
+        images: list[AnnotatedImage],
+        prompt: str,
+        context: ClinicalContext | None,
+    ) -> AnalysisResult:
+        """Run image analysis and return structured results."""

medcheck/llm/claude.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import base64
+import os
+from typing import Any
+
+from medcheck.core.context import ClinicalContext
+from medcheck.llm.base import AnalysisResult, AnnotatedImage, LLMProvider, parse_llm_response
+
+
+class ClaudeProvider(LLMProvider):
+    """Anthropic Claude provider."""
+
+    name = "claude"
+    supports_vision = True
+
+    def __init__(self, model: str = "claude-opus-4-7") -> None:
+        self.model = model
+
+    def check_available(self) -> bool:
+        return bool(os.environ.get("ANTHROPIC_API_KEY"))
+
+    def analyze_images(
+        self,
+        images: list[AnnotatedImage],
+        prompt: str,
+        context: ClinicalContext | None,
+    ) -> AnalysisResult:
+        import anthropic
+
+        api_key = os.environ.get("ANTHROPIC_API_KEY")
+        if not api_key:
+            raise RuntimeError("ANTHROPIC_API_KEY not set")
+        client = anthropic.Anthropic(api_key=api_key)
+
+        content: list[dict[str, Any]] = []
+        for img in images:
+            b64 = base64.standard_b64encode(img.image_bytes).decode()
+            content.append(
+                {
+                    "type": "image",
+                    "source": {
+                        "type": "base64",
+                        "media_type": "image/png",
+                        "data": b64,
+                    },
+                }
+            )
+            if img.description:
+                content.append({"type": "text", "text": img.description})
+
+        content.append({"type": "text", "text": prompt})
+
+        message = client.messages.create(
+            model=self.model,
+            max_tokens=4096,
+            messages=[{"role": "user", "content": content}],
+        )
+
+        raw = message.content[0].text
+        return parse_llm_response(raw)

medcheck/llm/gemini.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from medcheck.core.context import ClinicalContext
+from medcheck.llm.base import AnalysisResult, AnnotatedImage, LLMProvider, parse_llm_response
+
+
+class GeminiProvider(LLMProvider):
+    """Google Gemini provider."""
+
+    name = "gemini"
+    supports_vision = True
+
+    def __init__(self, model: str = "gemini-3.5-flash") -> None:
+        self.model = model
+
+    def check_available(self) -> bool:
+        return bool(os.environ.get("GOOGLE_API_KEY"))
+
+    def analyze_images(
+        self,
+        images: list[AnnotatedImage],
+        prompt: str,
+        context: ClinicalContext | None,
+    ) -> AnalysisResult:
+        import google.generativeai as genai
+
+        api_key = os.environ.get("GOOGLE_API_KEY")
+        if not api_key:
+            raise RuntimeError("GOOGLE_API_KEY not set")
+        genai.configure(api_key=api_key)
+        model = genai.GenerativeModel(self.model)
+
+        parts: list[Any] = []
+        for img in images:
+            parts.append({"mime_type": "image/png", "data": img.image_bytes})
+            if img.description:
+                parts.append(img.description)
+
+        parts.append(prompt)
+
+        response = model.generate_content(parts)
+        raw = response.text
+        return parse_llm_response(raw)

medcheck/llm/openai_provider.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import base64
+import os
+from typing import Any
+
+from medcheck.core.context import ClinicalContext
+from medcheck.llm.base import AnalysisResult, AnnotatedImage, LLMProvider, parse_llm_response
+
+
+class OpenAIProvider(LLMProvider):
+    """OpenAI GPT provider."""
+
+    name = "openai"
+    supports_vision = True
+
+    def __init__(self, model: str = "gpt-5.5") -> None:
+        self.model = model
+
+    def check_available(self) -> bool:
+        return bool(os.environ.get("OPENAI_API_KEY"))
+
+    def analyze_images(
+        self,
+        images: list[AnnotatedImage],
+        prompt: str,
+        context: ClinicalContext | None,
+    ) -> AnalysisResult:
+        from openai import OpenAI
+
+        api_key = os.environ.get("OPENAI_API_KEY")
+        if not api_key:
+            raise RuntimeError("OPENAI_API_KEY not set")
+        client = OpenAI(api_key=api_key)
+
+        content: list[dict[str, Any]] = []
+        for img in images:
+            b64 = base64.standard_b64encode(img.image_bytes).decode()
+            content.append(
+                {
+                    "type": "image_url",
+                    "image_url": {"url": f"data:image/png;base64,{b64}"},
+                }
+            )
+            if img.description:
+                content.append({"type": "text", "text": img.description})
+
+        content.append({"type": "text", "text": prompt})
+
+        response = client.chat.completions.create(
+            model=self.model,
+            messages=[{"role": "user", "content": content}],
+            max_tokens=4096,
+        )
+
+        raw = response.choices[0].message.content or ""
+        return parse_llm_response(raw)

medcheck/llm/router.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from medcheck.llm.base import LLMProvider
+
+FALLBACK_ORDER = ["claude", "openai", "gemini", "local"]
+
+
+class LLMRouter:
+    """Register LLM providers and select the best available one."""
+
+    def __init__(self) -> None:
+        self._providers: dict[str, LLMProvider] = {}
+
+    def register(self, provider: LLMProvider) -> None:
+        """Add a provider to the registry."""
+        self._providers[provider.name] = provider
+
+    def select(self, preferred: str) -> LLMProvider:
+        """Return the preferred provider if available, else fall back through
+        FALLBACK_ORDER, then any registered available provider."""
+        # Try the explicitly requested provider first.
+        preferred_provider = self._providers.get(preferred)
+        if preferred_provider and preferred_provider.check_available():
+            return preferred_provider
+
+        # Walk the canonical fallback order.
+        for name in FALLBACK_ORDER:
+            if name == preferred:
+                continue
+            provider = self._providers.get(name)
+            if provider and provider.check_available():
+                return provider
+
+        # Last resort: any registered provider that is available.
+        for provider in self._providers.values():
+            if provider.check_available():
+                return provider
+
+        raise RuntimeError("No LLM provider available")
+
+    def list_available(self) -> list[str]:
+        """Return names of all currently available providers."""
+        return [name for name, provider in self._providers.items() if provider.check_available()]