lithicore 0.4.1b0__py3-none-any.whl

lithicore/__init__.py

@@ -0,0 +1,111 @@
+"""lithicore — 3D lithic artefact morphological measurement library.
+
+exports: orient_auto(mesh, config) -> tuple[trimesh.Trimesh, np.ndarray]
+         orient_manual(mesh, points, config) -> tuple[trimesh.Trimesh, np.ndarray]
+         extract_metrics(mesh, config) -> list[MeasurementResult]
+         detect_edges(mesh, config) -> np.ndarray
+         platform_angles(mesh, config) -> tuple[MeasurementResult, MeasurementResult]
+         validate_mesh(mesh) -> MeshQualityReport
+         repair_mesh(mesh) -> trimesh.Trimesh
+         batch_process(directory, config) -> list[ArtefactResult]
+          PhotogrammetryConfig, PhotogrammetryResult, PhotogrammetryError,
+            ColmapNotFoundError, ColmapStageError, InsufficientPhotosError,
+            PhotogrammetryCancelledError, colmap_available, run_pipeline
+          ScaleResult, detect_scale_aruco, apply_scale_to_mesh
+used_by: lithicope GUI, CLI users
+rules:   No GUI imports. Every public function takes a mesh + config and returns typed results.
+agent:   deepseek-v4-flash | 2026-05-26 | Initial scaffolding
+         deepseek-v4-flash | 2026-05-26 | All modules wired — full public API exported
+         deepseek-v4-flash | 2026-05-26 | Added FigureConfig + generate_figure export
+         deepseek-v4-pro | 2026-06-12 | Added AssistantResult to __all__ and imports
+"""
+
+# pylint: disable=unused-import
+try:
+    from lithicore._models import (
+        MeasurementConfig,
+        MeasurementResult,
+        ArtefactResult,
+        Landmark,
+        MeshQualityReport,
+        MeshGrade,
+        ClassificationResult,
+        FeatureImportance,
+        LithicFeatureVector,
+        AssistantResult,
+    )
+    from lithicore._orientation import orient_auto, orient_manual
+    from lithicore._metrics import extract_metrics
+    from lithicore._edge_detection import detect_edges
+    from lithicore._platform_angle import platform_angles
+    from lithicore._validation import validate_mesh, repair_mesh
+    from lithicore._batch import batch_process
+    from lithicore._figure import FigureConfig, generate_figure
+    from lithicore._comparison import compare_meshes, ComparisonResult
+    from lithicore._photogrammetry import (
+        PhotogrammetryConfig,
+        PhotogrammetryResult,
+        PhotogrammetryError,
+        ColmapNotFoundError,
+        ColmapStageError,
+        InsufficientPhotosError,
+        PhotogrammetryCancelledError,
+        run_pipeline,
+        colmap_available,
+        clean_point_cloud,
+        ProgressCallback,
+    )
+    from lithicore._scale_detection import (
+        ScaleResult,
+        detect_scale_aruco,
+        apply_scale_to_mesh,
+    )
+    from lithicore._photo_preprocessing import (
+        PreprocessingConfig,
+        PreprocessingResult,
+        preprocess_photos,
+        compute_laplacian_variance,
+        compute_blur_scores,
+    )
+    from lithicore._annotations import (
+        Annotation,
+        AnnotationSet,
+    )
+    from lithicore._classification import (
+        ClassifierModel,
+        extract_features,
+        train_model,
+        extract_diagnostic_coordinates,
+    )
+    from lithicore._assistant import (
+        AssistantEngine,
+    )
+
+    __all__ = [
+        "MeasurementConfig", "MeasurementResult", "ArtefactResult", "Landmark",
+        "MeshQualityReport", "MeshGrade",
+        "orient_auto", "orient_manual",
+        "extract_metrics", "detect_edges", "platform_angles",
+        "validate_mesh", "repair_mesh", "batch_process",
+        "FigureConfig", "generate_figure",
+        "compare_meshes", "ComparisonResult",
+        "PhotogrammetryConfig", "PhotogrammetryResult",
+        "PhotogrammetryError", "ColmapNotFoundError", "ColmapStageError",
+        "InsufficientPhotosError", "PhotogrammetryCancelledError",
+        "run_pipeline", "colmap_available", "clean_point_cloud",
+        "ProgressCallback",
+        "ScaleResult", "detect_scale_aruco", "apply_scale_to_mesh",
+        "PreprocessingConfig", "PreprocessingResult",
+        "preprocess_photos", "compute_laplacian_variance", "compute_blur_scores",
+        "Annotation", "AnnotationSet",
+        "ClassificationResult", "FeatureImportance", "LithicFeatureVector",
+        "ClassifierModel", "extract_features", "train_model",
+        "extract_diagnostic_coordinates",
+        "AssistantEngine", "AssistantResult",
+    ]
+except ImportError as _exc:
+    # Forward reference — all modules exist since Phases 2-4
+    raise ImportError(
+        f"lithicore module import failed: {_exc}. "
+        "Try: pip install --no-deps -e lithicore"
+    ) from _exc

lithicore/_annotations.py

@@ -0,0 +1,181 @@
+"""_annotations.py — 3D mesh annotation data model.
+
+exports: Annotation
+         AnnotationSet
+used_by: lithicope annotation panel
+rules:   Pure dataclasses with JSON serialization. No GUI imports.
+         Coordinates are (x, y, z) floats matching mesh vertex space.
+agent:   deepseek-v4-flash | 2026-05-27 | Initial implementation
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class Annotation:
+    """A single annotation attached to a 3D mesh point.
+
+    Attributes:
+        point: (x, y, z) coordinates on the mesh surface.
+        title: Short label for the annotation.
+        description: Multi-line descriptive notes.
+        category: Type classification — e.g. "scar", "ridge",
+            "notch", "cortex", "flake", "breakage", "other".
+        measurement_mm: Optional numeric measurement at this point.
+        confidence: Estimated reliability (0 = uncertain, 1 = certain).
+        author: Name or identifier of the annotator.
+        timestamp: ISO 8601 datetime string of creation/last edit.
+        attached_photos: List of file paths to associated images.
+        sub_annotations: Child annotations nested under this one.
+    """
+    point: tuple[float, float, float]
+    title: str
+    description: str = ""
+    category: str = ""
+    measurement_mm: float = 0.0
+    confidence: float = 1.0
+    author: str = ""
+    timestamp: str = ""
+    attached_photos: list[str] = field(default_factory=list)
+    sub_annotations: list["Annotation"] = field(default_factory=list)
+
+
+@dataclass
+class AnnotationSet:
+    """A collection of annotations for a single artefact mesh.
+
+    Attributes:
+        format_version: Schema version for forward compatibility.
+        artefact_label: Human-readable artefact identifier.
+        mesh_path: Relative or absolute path to the associated mesh file.
+        mesh_checksum: SHA-256 hex digest of the mesh file for validation.
+        author: Name of the person who created this set.
+        created: ISO 8601 datetime of initial creation.
+        annotations: All top-level annotations for this artefact.
+    """
+    format_version: int = 1
+    artefact_label: str = ""
+    mesh_path: str = ""
+    mesh_checksum: str = ""
+    author: str = ""
+    created: str = ""
+    annotations: list[Annotation] = field(default_factory=list)
+
+    def to_json(self) -> str:
+        """Serialize this annotation set to a JSON string."""
+        data = asdict(self)
+        return json.dumps(data, indent=2, default=str)
+
+    @classmethod
+    def from_json(cls, data: str) -> AnnotationSet:
+        """Deserialize a JSON string into an AnnotationSet."""
+        raw = json.loads(data)
+        # Reconstruct nested Annotation objects
+        raw["annotations"] = [
+            cls._annotation_from_dict(a) for a in raw.get("annotations", [])
+        ]
+        return cls(**raw)
+
+    @staticmethod
+    def _annotation_from_dict(raw: dict) -> Annotation:
+        """Recursively build an Annotation from a dict, handling sub-annotations."""
+        subs = raw.pop("sub_annotations", [])
+        ann = Annotation(**raw)
+        ann.sub_annotations = [
+            AnnotationSet._annotation_from_dict(s) for s in subs
+        ]
+        return ann
+
+    @staticmethod
+    def _point_key(point: tuple[float, float, float]) -> tuple[float, float, float]:
+        """Round a 3D point to 3 decimal places for stable merge matching."""
+        return (round(point[0], 3), round(point[1], 3), round(point[2], 3))
+
+    def merge(self, other: AnnotationSet) -> tuple[AnnotationSet, list[str]]:
+        """Merge another AnnotationSet into this one.
+
+        Annotations at the same 3D position (rounded to 3 dp) are merged.
+        Unique positions are appended. Conflicts (same position, different
+        data) keep both entries with an author suffix and a warning.
+
+        Args:
+            other: The incoming annotation set to merge.
+
+        Returns:
+            A tuple of (merged AnnotationSet, list of warning strings).
+        """
+        warnings: list[str] = []
+        merged = AnnotationSet(
+            format_version=self.format_version,
+            artefact_label=self.artefact_label or other.artefact_label,
+            mesh_path=self.mesh_path or other.mesh_path,
+            mesh_checksum=self.mesh_checksum or other.mesh_checksum,
+            author=f"{self.author}+{other.author}" if self.author and other.author
+                   else self.author or other.author,
+            created=self.created or other.created,
+        )
+
+        # Index existing annotations by position key
+        existing: dict[tuple[float, float, float], Annotation] = {}
+        for ann in self.annotations:
+            existing[self._point_key(ann.point)] = ann
+
+        # Add all current annotations
+        merged.annotations = list(self.annotations)
+
+        for ann in other.annotations:
+            key = self._point_key(ann.point)
+            if key in existing:
+                existing_ann = existing[key]
+                # Conflict detection: same point, different title/desc
+                if (existing_ann.title != ann.title or
+                        existing_ann.description != ann.description):
+                    suffix = f" ({ann.author})" if ann.author else " (imported)"
+                    merged_ann = Annotation(
+                        point=ann.point,
+                        title=ann.title + suffix,
+                        description=ann.description,
+                        category=ann.category or existing_ann.category,
+                        measurement_mm=ann.measurement_mm or existing_ann.measurement_mm,
+                        confidence=ann.confidence or existing_ann.confidence,
+                        author=ann.author or existing_ann.author,
+                        timestamp=max(ann.timestamp, existing_ann.timestamp)
+                        if ann.timestamp and existing_ann.timestamp
+                        else ann.timestamp or existing_ann.timestamp,
+                        attached_photos=list(set(existing_ann.attached_photos + ann.attached_photos)),
+                    )
+                    # Replace in-place
+                    for i, e in enumerate(merged.annotations):
+                        if self._point_key(e.point) == key:
+                            merged.annotations[i] = merged_ann
+                            break
+                    warnings.append(
+                        f"Merged annotation at ({ann.point[0]:.3f}, {ann.point[1]:.3f}, "
+                        f"{ann.point[2]:.3f}): conflicting data resolved with author suffix"
+                    )
+                else:
+                    # Same content — prefer newer timestamp
+                    if ann.timestamp and (not existing_ann.timestamp or
+                                          ann.timestamp > existing_ann.timestamp):
+                        for i, e in enumerate(merged.annotations):
+                            if self._point_key(e.point) == key:
+                                e.timestamp = ann.timestamp
+                                e.author = ann.author or e.author
+                                break
+            else:
+                merged.annotations.append(ann)
+
+        return merged, warnings
+
+    def compute_checksum(self, mesh_path: Path) -> str:
+        """Compute SHA-256 hex digest of a mesh file."""
+        sha = hashlib.sha256()
+        with open(mesh_path, "rb") as f:
+            for chunk in iter(lambda: f.read(65536), b""):
+                sha.update(chunk)
+        return f"sha256:{sha.hexdigest()}"

lithicore/_assistant.py

@@ -0,0 +1,311 @@
+"""_assistant.py — AI-powered natural language query engine for lithic collections.
+
+exports: AssistantEngine
+used_by: lithicope assistant panel
+rules:   No GUI imports. DuckDB queries are read-only SELECT. LLM is optional dependency.
+         All functions safe to call when model not loaded (returns error result).
+agent:   deepseek-v4-flash | 2026-05-27 | Initial implementation
+         deepseek-v4-pro | 2026-06-12 | Added _validate_sql() safety gate rejecting non-SELECT, multi-statement, and dangerous keywords
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+from typing import Callable, Optional
+
+import numpy as np
+import pandas as pd
+
+from lithicore._models import AssistantResult
+
+
+MODEL_DIR = Path.home() / ".dibble" / "models" / "assistant"
+MODEL_FILENAME = "qwen3-4b-q4_k_m.gguf"
+GRAMMAR_DIR = Path(__file__).resolve().parent.parent / "data" / "grammars"
+SQL_GRAMMAR_PATH = GRAMMAR_DIR / "sql_query.gbnf"
+
+
+SCHEMA_DESCRIPTION = """
+Table: artifacts
+Columns:
+  - length_mm (FLOAT) — maximum length in mm
+  - width_mm (FLOAT) — maximum width in mm
+  - thickness_mm (FLOAT) — maximum thickness in mm
+  - surface_area_mm2 (FLOAT) — total surface area
+  - volume_mm3 (FLOAT) — total volume
+  - elongation (FLOAT) — length/width ratio
+  - flatness (FLOAT) — width/thickness ratio
+  - compactness (FLOAT) — volume/length^3
+  - relative_thickness (FLOAT) — thickness/length
+  - scar_count (INTEGER) — number of flake scars detected
+  - mean_scar_area_mm2 (FLOAT) — average scar area
+  - platform_angle_deg (FLOAT) — platform angle in degrees
+  - edge_angle_mean_deg (FLOAT) — mean edge angle
+  - edge_angle_std_deg (FLOAT) — edge angle std deviation
+  - curvature_index (FLOAT) — dorsal curvature
+  - cross_section_profile (FLOAT) — 0=flat, 1=triangular, 2=round
+  - symmetry_score (FLOAT) — bilateral symmetry (0-1)
+  - com_z_ratio (FLOAT) — centre of mass height ratio
+  - dorsal_ridge_count (INTEGER) — number of parallel ridges
+  - surface_roughness (FLOAT) — texture metric
+  - typology (TEXT) — predicted type
+  - artefact_label (TEXT) — user-assigned name
+"""
+
+FEW_SHOT_EXAMPLES = """
+-- Example 1: "show me all blades longer than 100mm"
+SELECT * FROM artifacts WHERE typology = 'Blade' AND length_mm > 100 LIMIT 50;
+
+-- Example 2: "what's the average platform angle of crested blades?"
+SELECT AVG(platform_angle_deg) FROM artifacts WHERE typology = 'Crested blade';
+
+-- Example 3: "find the 5 most symmetrical handaxes"
+SELECT * FROM artifacts WHERE typology = 'Handaxe' ORDER BY symmetry_score DESC LIMIT 5;
+"""
+
+
+class AssistantEngine:
+    """LLM-powered natural language query engine for lithic collections."""
+
+    def __init__(self) -> None:
+        self._llm = None
+        self._grammar: Optional[str] = None
+        self._model_available = False
+
+    def load_model(self, progress_cb: Optional[Callable] = None) -> None:
+        """Load the LLM model. Downloads from HuggingFace if not cached."""
+        try:
+            import llama_cpp
+        except ImportError:
+            if progress_cb:
+                progress_cb("error", 0.0, "llama-cpp-python not installed")
+            return
+
+        model_path = MODEL_DIR / MODEL_FILENAME
+        MODEL_DIR.mkdir(parents=True, exist_ok=True)
+
+        if not model_path.exists():
+            if progress_cb:
+                progress_cb("download", 0.0, "Downloading model (~2.5GB)...")
+            try:
+                self._llm = llama_cpp.Llama.from_pretrained(
+                    repo_id="Qwen/Qwen3-4B-GGUF",
+                    filename="*q4_k_m.gguf",
+                    verbose=False,
+                )
+            except Exception as exc:
+                if progress_cb:
+                    progress_cb("error", 0.0, f"Download failed: {exc}")
+                return
+        else:
+            if progress_cb:
+                progress_cb("loading", 0.0, "Loading model...")
+            try:
+                self._llm = llama_cpp.Llama(
+                    model_path=str(model_path),
+                    n_ctx=4096,
+                    n_threads=os.cpu_count() or 4,
+                    verbose=False,
+                )
+            except Exception as exc:
+                if progress_cb:
+                    progress_cb("error", 0.0, f"Model load failed: {exc}")
+                return
+
+        if SQL_GRAMMAR_PATH.exists():
+            self._grammar = SQL_GRAMMAR_PATH.read_text()
+
+        self._model_available = True
+        if progress_cb:
+            progress_cb("ready", 1.0, "AI assistant ready")
+
+    def is_loaded(self) -> bool:
+        """Check if the model is ready for queries."""
+        return self._model_available and self._llm is not None
+
+    def _validate_sql(self, sql: str) -> bool:
+        """Validate that a generated SQL string is a safe SELECT query.
+
+        Rejects non-SELECT statements, multi-statement queries, and queries
+        that reference system tables. This is a hard safety gate independent
+        of the GBNF grammar.
+        """
+        stripped = sql.strip().upper()
+        if not stripped.startswith("SELECT"):
+            return False
+        if ";" in stripped[:-1]:
+            return False  # Multi-statement — potential injection
+        # Reject dangerous keywords outside of quotes
+        forbidden = {"DROP", "DELETE", "INSERT", "UPDATE", "ALTER", "CREATE",
+                      "TRUNCATE", "EXEC", "EXECUTE", "ATTACH", "DETACH",
+                      "PRAGMA", "IMPORT", "EXPORT"}
+        words = set(stripped.replace("(", " ").replace(")", " ").replace(",", " ").split())
+        if words & forbidden:
+            return False
+        return True
+
+    def query(self, user_text: str, collection_df: pd.DataFrame) -> AssistantResult:
+        """Run the full query loop: natural language -> SQL -> execute -> explain.
+
+        Args:
+            user_text: The user's natural language query.
+            collection_df: In-memory DataFrame of the current artefact collection.
+
+        Returns:
+            AssistantResult with natural_language explanation, sql_query, row_count.
+        """
+        import duckdb
+
+        if not self.is_loaded():
+            return AssistantResult(
+                error="AI model not loaded. Use Assistant > Download Model to set up.",
+                processing_time_s=0.0,
+            )
+
+        if collection_df.empty:
+            return AssistantResult(
+                natural_language="No artefacts in the current collection to query.",
+                processing_time_s=0.0,
+            )
+
+        start = time.time()
+
+        # Step 1: Build prompt
+        prompt = self._build_sql_prompt(user_text, collection_df)
+
+        # Step 2: Generate SQL with GBNF grammar
+        sql = self._generate_sql(prompt)
+        if sql is None:
+            return AssistantResult(
+                error="Failed to generate a valid SQL query.",
+                processing_time_s=round(time.time() - start, 2),
+            )
+
+        if not self._validate_sql(sql):
+            return AssistantResult(
+                sql_query=sql,
+                error="Generated SQL query was rejected by safety validator.",
+                processing_time_s=round(time.time() - start, 2),
+            )
+
+        # Step 3: Self-correcting execution loop
+        result_df = None
+        last_error = ""
+        for attempt in range(3):
+            try:
+                result_df = duckdb.sql(sql).df()
+                break
+            except Exception as exc:
+                last_error = str(exc)
+                if attempt < 2:
+                    sql = self._fix_sql(prompt, sql, last_error)
+
+        elapsed = time.time() - start
+
+        if result_df is None:
+            return AssistantResult(
+                sql_query=sql,
+                error=f"SQL execution failed after 3 attempts: {last_error}",
+                processing_time_s=round(elapsed, 2),
+            )
+
+        # Step 4: Summarize results
+        summary = self._summarize_results(user_text, result_df)
+
+        return AssistantResult(
+            natural_language=summary or f"Found {len(result_df)} matching artefacts.",
+            sql_query=sql,
+            row_count=len(result_df),
+            processing_time_s=round(elapsed, 2),
+        )
+
+    def _build_sql_prompt(self, user_text: str, df: pd.DataFrame) -> str:
+        """Build the system prompt with schema and user query."""
+        return (
+            "You are a SQL query generator for a lithic (stone tool) analysis database. "
+            "Generate ONLY a DuckDB SQL SELECT query. No explanations, no markdown.\n\n"
+            f"Schema:\n{SCHEMA_DESCRIPTION}\n\n"
+            f"Examples:\n{FEW_SHOT_EXAMPLES}\n\n"
+            f"Table has {len(df)} rows.\n\n"
+            f"User query: {user_text}\n\n"
+            "SQL:"
+        )
+
+    def _generate_sql(self, prompt: str) -> Optional[str]:
+        """Generate SQL constrained by GBNF grammar."""
+        try:
+            output = self._llm.create_completion(
+                prompt,
+                max_tokens=256,
+                temperature=0.1,
+                grammar=self._grammar,
+                stop=[";"],
+            )
+            text = output["choices"][0]["text"].strip()
+            if not text.endswith(";"):
+                text += ";"
+            return text
+        except Exception:
+            return None
+
+    def _fix_sql(self, prompt: str, bad_sql: str, error: str) -> Optional[str]:
+        """Fix a SQL error by appending the error and regenerating."""
+        fix_prompt = (
+            f"{prompt}\n\n"
+            f"Previous (failed) SQL: {bad_sql}\n"
+            f"Error: {error}\n"
+            "Fixed SQL:"
+        )
+        return self._generate_sql(fix_prompt)
+
+    def _summarize_results(self, user_text: str, df: pd.DataFrame) -> Optional[str]:
+        """Generate a natural language summary of query results."""
+        if df.empty:
+            return "No artefacts matched your query."
+
+        numeric_cols = df.select_dtypes(include=[np.number]).columns
+        stats = {}
+        for col in list(numeric_cols)[:5]:
+            stats[col] = {
+                "mean": round(float(df[col].mean()), 1),
+                "min": round(float(df[col].min()), 1),
+                "max": round(float(df[col].max()), 1),
+            }
+
+        type_counts = {}
+        if "typology" in df.columns:
+            type_counts = df["typology"].value_counts().head(5).to_dict()
+
+        summary_prompt = (
+            "Summarize these lithic analysis results in 1-3 concise sentences.\n"
+            f"User asked: {user_text}\n"
+            f"Found {len(df)} matching artefacts.\n"
+            f"Summary stats: {stats}\n"
+            f"Typology breakdown: {type_counts}\n\n"
+            "Response:"
+        )
+
+        try:
+            output = self._llm.create_completion(
+                summary_prompt,
+                max_tokens=200,
+                temperature=0.3,
+                stop=["\n\n"],
+            )
+            return output["choices"][0]["text"].strip()
+        except Exception:
+            return None
+
+    @staticmethod
+    def get_model_status() -> dict:
+        """Return model status info for the UI."""
+        model_path = MODEL_DIR / MODEL_FILENAME
+        size_mb = round(model_path.stat().st_size / (1024 * 1024), 1) if model_path.exists() else 0
+        return {
+            "installed": model_path.exists(),
+            "size_mb": size_mb,
+            "path": str(model_path),
+            "grammar_exists": SQL_GRAMMAR_PATH.exists(),
+        }