groundly 0.3.0__py3-none-any.whl

groundly/cli/__init__.py

@@ -0,0 +1,261 @@
+"""Groundly CLI — batch lifecycle verbs; the host agent is the interactive surface.
+
+Command surface per docs/superpowers/specs/2026-07-16-p1-cli-surface-design.md.
+Later phases add verbs: P2 import/export · P3 ask · P4 mcp/serve · P6 export-deck.
+"""
+
+from importlib.metadata import version as _package_version
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+from rich.console import Console
+from rich.markup import escape
+from rich.table import Table
+
+app = typer.Typer(
+    no_args_is_help=True,
+    add_completion=False,
+    help="Groundly — local course knowledge bases for AI agents.",
+)
+config_app = typer.Typer()
+app.add_typer(config_app, name="config")
+
+console = Console()
+
+
+def _fail(message: str) -> None:
+    console.print(f"[red]error:[/red] {escape(message)}")
+    raise typer.Exit(code=1)
+
+
+def _subject_dir_checked(subject: str) -> Path:
+    from groundly.core.paths import subject_dir
+
+    try:
+        sdir = subject_dir(subject)
+    except ValueError as exc:
+        _fail(str(exc))
+    if not (sdir / "manifest.json").exists():
+        _fail(f"subject '{subject}' is not initialized — run: groundly init {subject}")
+    return sdir
+
+
+def _connect_checked(sdir: Path):
+    from groundly.core import store
+
+    try:
+        return store.connect(sdir / "store.db")
+    except RuntimeError as exc:  # missing store.db / newer schema — named cause, no traceback
+        _fail(str(exc))
+
+
+def _not_implemented(verb: str) -> None:
+    typer.echo(f"groundly {verb}: not implemented yet — arrives in a later phase")
+    raise typer.Exit(code=1)
+
+
+def _print_version(value: bool) -> None:
+    if value:
+        typer.echo(_package_version("groundly"))
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version", callback=_print_version, is_eager=True, help="Print version and exit."
+        ),
+    ] = False,
+) -> None:
+    """Groundly — local-first course knowledge bases for AI agents."""
+
+
+@app.command()
+def init(
+    subject: Annotated[str, typer.Argument(help="Subject name; becomes ~/.groundly/<SUBJECT>/.")],
+) -> None:
+    """Create a subject: manifest.json, materials/, store.db, progress.db."""
+    from groundly.core.subject import init_subject
+
+    try:
+        sdir, created = init_subject(subject)
+    except ValueError as exc:
+        _fail(str(exc))
+    if created:
+        console.print(f"initialized [bold]{subject}[/bold] at {sdir}")
+    else:
+        console.print(f"[bold]{subject}[/bold] already initialized at {sdir}")
+
+
+@app.command()
+def index(
+    subject: Annotated[str, typer.Argument(help="Subject to index into (must be initialized).")],
+    paths: Annotated[list[Path], typer.Argument(help="Files or directories to index.")],
+) -> None:
+    """Index course materials: hash-skip idempotent, per-file progress, resumable."""
+    from groundly.ingestion import pipeline
+
+    labels = {
+        pipeline.INDEXED: "[green]indexed[/green]",
+        pipeline.SKIPPED_DUPLICATE: "[dim]skipped (already indexed)[/dim]",
+        pipeline.SKIPPED_UNSUPPORTED: "[yellow]skipped[/yellow]",
+        pipeline.SKIPPED_FAILED: "[yellow]skipped[/yellow]",
+        pipeline.EXTRACTION_FAILED: "[red]failed[/red]",
+        pipeline.ERROR: "[red]error[/red]",
+    }
+
+    with console.status("indexing…") as status:
+
+        def on_event(path: Path, stage: str) -> None:
+            if stage in ("extracting", "embedding"):
+                status.update(f"{path.name}: {stage}…")
+
+        try:
+            results = pipeline.index_paths(subject, paths, on_event=on_event)
+        except (RuntimeError, ValueError) as exc:
+            _fail(str(exc))
+
+    for r in results:
+        # filenames and parser errors are document-influenced — never live markup
+        detail = f" — {escape(r.detail)}" if r.detail else ""
+        chunks = f" ({r.chunks} chunks)" if r.status == pipeline.INDEXED else ""
+        console.print(f"  {escape(r.path.name)}: {labels[r.status]}{chunks}{detail}")
+
+    indexed = sum(r.status == pipeline.INDEXED for r in results)
+    failed = sum(r.status in (pipeline.EXTRACTION_FAILED, pipeline.ERROR) for r in results)
+    console.print(f"{indexed} indexed, {len(results) - indexed - failed} skipped, {failed} failed")
+    if failed:
+        raise typer.Exit(code=1)
+
+
+@app.command(name="list")
+def list_(
+    subject: Annotated[
+        Optional[str],
+        typer.Argument(help="Subject to inspect; omit to list all subjects."),
+    ] = None,
+) -> None:
+    """List subjects, or one subject's materials with status, pages, chunks."""
+    import sqlite3
+
+    from pydantic import ValidationError
+
+    from groundly.core import store
+    from groundly.core.manifest import Manifest
+    from groundly.core.paths import discover_subjects, subject_dir
+
+    if subject is None:
+        table = Table("subject", "materials", "chunks")
+        for name in discover_subjects():
+            try:
+                manifest = Manifest.load(subject_dir(name) / "manifest.json")
+            except ValidationError:
+                # one damaged subject must not take down the whole listing
+                console.print(f"[red]warning:[/red] {name}: manifest.json is corrupt — skipping")
+                continue
+            table.add_row(name, str(manifest.counts.materials), str(manifest.counts.chunks))
+        console.print(table)
+        return
+
+    sdir = _subject_dir_checked(subject)
+    conn = _connect_checked(sdir)
+    try:
+        table = Table("material", "status", "pages", "chunks", "detail")
+        for row in store.list_materials(conn):
+            table.add_row(
+                escape(row["filename"]),
+                row["status"],
+                str(row["pages"] or "—"),
+                str(row["chunk_count"]),
+                escape(row["error"] or ""),
+            )
+        console.print(table)
+    except sqlite3.OperationalError as exc:
+        _fail(f"store.db is corrupt or incomplete: {exc}")
+    finally:
+        conn.close()
+
+
+@app.command()
+def remove(
+    subject: Annotated[str, typer.Argument(help="Subject the material belongs to.")],
+    material: Annotated[
+        Optional[str],
+        typer.Argument(
+            help="Material filename (or sha256 prefix) as shown by `groundly list`; "
+            "omit to remove the whole subject."
+        ),
+    ] = None,
+    yes: Annotated[bool, typer.Option("--yes", "-y", help="Skip the confirmation prompt.")] = False,
+) -> None:
+    """Remove a material and all its indexed data, or a whole subject if no material given."""
+    import sqlite3
+
+    from groundly.core import store
+    from groundly.core.manifest import sync_counts
+
+    sdir = _subject_dir_checked(subject)
+
+    if material is None:
+        import shutil
+
+        if not yes:
+            typer.confirm(
+                f"remove subject {subject} and ALL its data (materials, index, progress, notes)?",
+                abort=True,
+            )
+        shutil.rmtree(sdir)
+        console.print(f"removed subject [bold]{subject}[/bold]")
+        return
+
+    conn = _connect_checked(sdir)
+    try:
+        matches = store.find_materials(conn, material)
+        if not matches:
+            _fail(f"no material {material!r} in {subject} — see: groundly list {subject}")
+        if len(matches) > 1:
+            candidates = ", ".join(f"{m['filename']} ({m['sha256'][:8]})" for m in matches)
+            _fail(f"{material!r} is ambiguous — candidates: {candidates}; use a sha256 prefix")
+        target = matches[0]
+        if not yes:
+            typer.confirm(
+                f"remove {target['filename']} and all its indexed data from {subject}?",
+                abort=True,
+            )
+        store.remove_material(conn, target["id"])
+        sync_counts(conn, sdir / "manifest.json")
+        if target["status"] == "indexed":
+            # failed rows never got a copy in materials/, and their original filename
+            # (no collision suffix) can shadow a different indexed material's file
+            stored = sdir / "materials" / target["filename"]
+            if stored.exists():
+                stored.unlink()
+        console.print(f"removed [bold]{escape(target['filename'])}[/bold] from {subject}")
+        if (sdir / "graph").exists():
+            console.print(
+                "[dim]note: the graph is now stale — it rebuilds on the next"
+                " corpus-hash-triggered index run[/dim]"
+            )
+    except sqlite3.OperationalError as exc:
+        _fail(f"store.db is corrupt or incomplete: {exc}")
+    finally:
+        conn.close()
+
+
+@config_app.callback(invoke_without_command=True)
+def config(ctx: typer.Context) -> None:
+    """Show the config file path and effective values per call class (keys masked)."""
+    if ctx.invoked_subcommand is None:
+        _not_implemented("config")
+
+
+@config_app.command(name="set")
+def config_set(
+    key: Annotated[str, typer.Argument(help="Dotted key, e.g. chat.model or chat.base_url.")],
+    value: Annotated[str, typer.Argument(help="Value to set.")],
+) -> None:
+    """Set a provider config value in ~/.groundly/config.toml."""
+    _not_implemented("config set")

groundly/core/manifest.py

@@ -0,0 +1,76 @@
+"""manifest.json — the interchange contract (docs/architecture/data-model.md).
+
+The embedding pin (model + hf_revision + dim + normalization) decides whether shared
+vectors transfer as-is; changing it is a full re-index migration, never a tweak.
+"""
+
+import sqlite3
+from importlib.metadata import version as _package_version
+from pathlib import Path
+
+from pydantic import BaseModel
+
+FORMAT_VERSION = 1
+EMBEDDING_MODEL = "BAAI/bge-m3"
+HF_REVISION = "5617a9f61b028005a4858fdac845db406aefb181"  # pinned 2026-07-16 (P1 start)
+EMBEDDING_DIM = 1024
+CHUNK_MAX_TOKENS = 512
+CHUNK_OVERLAP = 0  # HybridChunker is structure-aware (split+merge); it has no token overlap
+
+
+class Embedding(BaseModel):
+    model: str = EMBEDDING_MODEL
+    hf_revision: str = HF_REVISION
+    dim: int = EMBEDDING_DIM
+    dtype: str = "float32"
+    normalized: bool = True
+
+
+class Graphrag(BaseModel):
+    version: str | None = None
+    extraction_model: str | None = None
+
+
+class Chunking(BaseModel):
+    strategy: str = "docling-hybrid"
+    max_tokens: int = CHUNK_MAX_TOKENS
+    overlap: int = CHUNK_OVERLAP
+
+
+class Counts(BaseModel):
+    materials: int = 0
+    chunks: int = 0
+
+
+class Manifest(BaseModel):
+    format_version: int = FORMAT_VERSION
+    subject: str
+    embedding: Embedding = Embedding()
+    graphrag: Graphrag = Graphrag()
+    chunking: Chunking = Chunking()
+    counts: Counts = Counts()
+    tool_version: str = ""
+
+    @classmethod
+    def new(cls, subject: str) -> "Manifest":
+        return cls(subject=subject, tool_version=_package_version("groundly"))
+
+    @classmethod
+    def load(cls, path: Path) -> "Manifest":
+        return cls.model_validate_json(path.read_text())
+
+    def save(self, path: Path) -> None:
+        # write-then-rename: a Ctrl-C or concurrent save never leaves torn JSON behind
+        tmp = path.with_suffix(".json.tmp")
+        tmp.write_text(self.model_dump_json(indent=2) + "\n")
+        tmp.replace(path)
+
+
+def sync_counts(conn: sqlite3.Connection, manifest_path: Path) -> None:
+    """Keep manifest counts in sync after every mutation (UC-03 acceptance)."""
+    manifest = Manifest.load(manifest_path)
+    manifest.counts.materials = conn.execute(
+        "SELECT COUNT(*) FROM materials WHERE status = 'indexed'"
+    ).fetchone()[0]
+    manifest.counts.chunks = conn.execute("SELECT COUNT(*) FROM chunks").fetchone()[0]
+    manifest.save(manifest_path)

groundly/core/paths.py

@@ -0,0 +1,33 @@
+"""Filesystem layout: ~/.groundly/ (GROUNDLY_HOME overrides), one dir per subject.
+
+Discovery scans */manifest.json — no registry database (docs/architecture/data-model.md).
+"""
+
+import os
+import re
+from pathlib import Path
+
+_SUBJECT_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]*$")
+
+
+def groundly_home() -> Path:
+    override = os.environ.get("GROUNDLY_HOME")
+    return Path(override) if override else Path.home() / ".groundly"
+
+
+def validate_subject_name(name: str) -> None:
+    """Subject names become path components and MCP identifiers."""
+    if not _SUBJECT_RE.fullmatch(name):  # fullmatch: `$` alone accepts a trailing newline
+        raise ValueError(
+            f"invalid subject name {name!r} — use letters, digits, '-' or '_' "
+            "(it becomes a directory name)"
+        )
+
+
+def subject_dir(name: str) -> Path:
+    validate_subject_name(name)
+    return groundly_home() / name
+
+
+def discover_subjects() -> list[str]:
+    return sorted(p.parent.name for p in groundly_home().glob("*/manifest.json"))

groundly/core/store.py

@@ -0,0 +1,143 @@
+"""store.db / progress.db access. Schema versioned via PRAGMA user_version — no
+migration framework; refuse to open a newer schema than this tool understands.
+
+Every connection gets WAL + busy_timeout: one-shot CLI runs and host-spawned MCP
+processes share the same files (.claude/rules/architecture.md).
+"""
+
+import sqlite3
+from pathlib import Path
+
+import sqlite_vec
+
+from groundly.core.manifest import EMBEDDING_DIM
+
+STORE_USER_VERSION = 1
+
+_SCHEMA = f"""
+CREATE TABLE materials (
+    id INTEGER PRIMARY KEY,
+    filename TEXT NOT NULL,
+    sha256 TEXT NOT NULL UNIQUE,
+    status TEXT NOT NULL CHECK (status IN ('indexed', 'extraction_failed')),
+    pages INTEGER,
+    error TEXT,
+    indexed_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE chunks (
+    id INTEGER PRIMARY KEY,
+    material_id INTEGER NOT NULL REFERENCES materials(id) ON DELETE CASCADE,
+    page INTEGER,
+    heading_path TEXT,
+    text TEXT NOT NULL,
+    token_count INTEGER
+);
+CREATE INDEX idx_chunks_material ON chunks(material_id);
+
+-- rowid = chunks.id; vec0 has no FK support, deletion is explicit in remove_material
+CREATE VIRTUAL TABLE vectors USING vec0(embedding float[{EMBEDDING_DIM}]);
+
+CREATE TABLE sparse_terms (
+    token_id INTEGER NOT NULL,
+    chunk_id INTEGER NOT NULL REFERENCES chunks(id) ON DELETE CASCADE,
+    weight REAL NOT NULL
+);
+CREATE INDEX idx_sparse_token ON sparse_terms(token_id);
+CREATE INDEX idx_sparse_chunk ON sparse_terms(chunk_id);
+
+CREATE VIRTUAL TABLE chunks_fts USING fts5(text, content='chunks', content_rowid='id');
+CREATE TRIGGER chunks_ai AFTER INSERT ON chunks BEGIN
+    INSERT INTO chunks_fts(rowid, text) VALUES (new.id, new.text);
+END;
+CREATE TRIGGER chunks_ad AFTER DELETE ON chunks BEGIN
+    INSERT INTO chunks_fts(chunks_fts, rowid, text) VALUES ('delete', old.id, old.text);
+END;
+CREATE TRIGGER chunks_au AFTER UPDATE ON chunks BEGIN
+    INSERT INTO chunks_fts(chunks_fts, rowid, text) VALUES ('delete', old.id, old.text);
+    INSERT INTO chunks_fts(rowid, text) VALUES (new.id, new.text);
+END;
+"""
+
+
+def connect(path: Path, create: bool = False) -> sqlite3.Connection:
+    if not create and not path.exists():
+        # sqlite3.connect would silently create an empty db — surface the real cause
+        raise RuntimeError(f"{path.name} is missing from {path.parent} — the subject is damaged")
+    conn = sqlite3.connect(path)
+    conn.row_factory = sqlite3.Row
+    conn.enable_load_extension(True)
+    sqlite_vec.load(conn)
+    conn.enable_load_extension(False)
+    conn.execute("PRAGMA journal_mode = WAL")
+    conn.execute("PRAGMA busy_timeout = 5000")
+    conn.execute("PRAGMA foreign_keys = ON")
+    version = conn.execute("PRAGMA user_version").fetchone()[0]
+    if version > STORE_USER_VERSION:
+        conn.close()
+        raise RuntimeError(
+            f"{path.name} has schema version {version}, newer than this groundly "
+            f"understands (max {STORE_USER_VERSION}) — upgrade groundly"
+        )
+    return conn
+
+
+def create_store(path: Path) -> None:
+    conn = connect(path, create=True)
+    try:
+        conn.executescript(_SCHEMA)
+        conn.execute(f"PRAGMA user_version = {STORE_USER_VERSION}")
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def create_progress(path: Path) -> None:
+    # Tables arrive in P3 (traces) / P6 (quiz_events, notes); progress.db never
+    # travels, so its schema can grow locally without interchange impact.
+    conn = sqlite3.connect(path)
+    try:
+        conn.execute("PRAGMA journal_mode = WAL")
+        conn.execute("PRAGMA busy_timeout = 5000")
+        conn.execute("PRAGMA user_version = 1")
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def list_materials(conn: sqlite3.Connection) -> list[sqlite3.Row]:
+    return conn.execute(
+        """
+        SELECT m.id, m.filename, m.sha256, m.status, m.pages, m.error,
+               COUNT(c.id) AS chunk_count
+        FROM materials m LEFT JOIN chunks c ON c.material_id = m.id
+        GROUP BY m.id ORDER BY m.filename
+        """
+    ).fetchall()
+
+
+def hash_status(conn: sqlite3.Connection) -> dict[str, str]:
+    """sha256 -> status, for hash-skip (indexed) and retry (extraction_failed)."""
+    return {r["sha256"]: r["status"] for r in conn.execute("SELECT sha256, status FROM materials")}
+
+
+def find_materials(conn: sqlite3.Connection, ident: str) -> list[sqlite3.Row]:
+    """Match by exact filename or sha256 prefix (the disambiguator)."""
+    escaped = ident.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+    return conn.execute(
+        "SELECT * FROM materials WHERE filename = ? OR sha256 LIKE ? ESCAPE '\\' ORDER BY filename",
+        (ident, escaped + "%"),
+    ).fetchall()
+
+
+def remove_material(conn: sqlite3.Connection, material_id: int) -> None:
+    """One transaction. FTS syncs via the chunks_ad trigger; sparse_terms via FK
+    cascade; vectors (vec0, no FK) deleted explicitly by chunk rowid."""
+    with conn:
+        chunk_ids = [
+            r["id"]
+            for r in conn.execute("SELECT id FROM chunks WHERE material_id = ?", (material_id,))
+        ]
+        conn.executemany("DELETE FROM vectors WHERE rowid = ?", [(cid,) for cid in chunk_ids])
+        conn.execute("DELETE FROM chunks WHERE material_id = ?", (material_id,))
+        conn.execute("DELETE FROM materials WHERE id = ?", (material_id,))

groundly/core/subject.py

@@ -0,0 +1,44 @@
+"""Subject lifecycle: create the on-disk layout that everything else assumes."""
+
+from pathlib import Path
+
+from groundly.core import store
+from groundly.core.manifest import Manifest
+from groundly.core.paths import subject_dir, groundly_home
+
+_CONFIG_TEMPLATE = """\
+# Groundly provider config — one OpenAI-compatible endpoint per call class.
+# All classes are optional: indexing and search work with no provider at all.
+#
+# [providers.chat]        # ask pipeline generation
+# base_url = "http://localhost:1234/v1"
+# model    = "..."
+# api_key  = "..."
+#
+# [providers.generation]  # exam/deck generation (thick path)
+# [providers.extraction]  # graphrag entity extraction
+# [providers.router]      # cheap query classifier
+"""
+
+
+def init_subject(name: str) -> tuple[Path, bool]:
+    """Create ~/.groundly/<name>/ (manifest, materials/, store.db, progress.db).
+
+    Returns (subject_dir, created); created=False if already initialized (idempotent).
+    Also writes the top-level config.toml template on first ever init.
+    """
+    sdir = subject_dir(name)
+    manifest_path = sdir / "manifest.json"
+    if manifest_path.exists():
+        return sdir, False
+
+    sdir.mkdir(parents=True, exist_ok=True)
+    (sdir / "materials").mkdir(exist_ok=True)
+    store.create_store(sdir / "store.db")
+    store.create_progress(sdir / "progress.db")
+    Manifest.new(name).save(manifest_path)
+
+    config_path = groundly_home() / "config.toml"
+    if not config_path.exists():
+        config_path.write_text(_CONFIG_TEMPLATE)
+    return sdir, True

groundly/ingestion/extract.py

@@ -0,0 +1,89 @@
+"""Parent side of extraction: spawn the worker, enforce a wall-clock timeout,
+map failures to specific user-facing causes (conventions: never generic errors).
+
+security.md §3 controls: argv exec (no shell), temp working directory, wall-clock
+timeout, output size cap — the worker's stdout is discarded, stderr goes to a file
+on disk (never an in-memory buffer) and only its tail is ever read."""
+
+import json
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from groundly.ingestion import extract_worker
+
+EXTRACT_TIMEOUT_SECONDS = 300
+STDERR_TAIL_BYTES = 4096
+MAX_EXTRACTION_JSON_BYTES = 200 * 1024 * 1024  # far beyond any real textbook
+
+
+@dataclass
+class ChunkData:
+    text: str
+    heading_path: str | None
+    page: int | None
+    token_count: int
+
+
+@dataclass
+class Extraction:
+    pages: int | None
+    chunks: list[ChunkData]
+
+
+class ExtractionFailure(Exception):
+    """reason is user-facing and names the specific cause."""
+
+
+class ModelUnavailable(Exception):
+    """The worker couldn't load its model (uncached + offline, HF rate-limit, missing
+    dep). Transient, not the document's fault — the pipeline retries, records no row."""
+
+
+def _stderr_tail(path: Path) -> str:
+    with open(path, "rb") as f:
+        f.seek(max(0, path.stat().st_size - STDERR_TAIL_BYTES))
+        lines = [ln for ln in f.read().decode(errors="replace").strip().splitlines() if ln.strip()]
+    return lines[-1] if lines else ""
+
+
+def extract(path: Path, timeout: float = EXTRACT_TIMEOUT_SECONDS) -> Extraction:
+    with tempfile.TemporaryDirectory() as tmp:
+        out_json = Path(tmp) / "extraction.json"
+        stderr_path = Path(tmp) / "stderr.log"
+        with open(stderr_path, "wb") as stderr_file:
+            try:
+                proc = subprocess.run(
+                    [
+                        sys.executable,
+                        "-m",
+                        "groundly.ingestion.extract_worker",
+                        str(
+                            path.resolve()
+                        ),  # worker runs with cwd=tmp; relative paths must survive
+                        str(out_json),
+                    ],
+                    stdout=subprocess.DEVNULL,
+                    stderr=stderr_file,
+                    cwd=tmp,
+                    timeout=timeout,
+                )
+            except subprocess.TimeoutExpired:
+                raise ExtractionFailure(f"extraction timed out after {int(timeout)}s") from None
+
+        if proc.returncode == extract_worker.EXIT_MODEL_UNAVAILABLE:
+            raise ModelUnavailable(_stderr_tail(stderr_path) or "extractor model unavailable")
+        if proc.returncode == extract_worker.EXIT_NO_TEXT:
+            if path.suffix.lower() == ".pdf":
+                raise ExtractionFailure("scanned PDF — not supported")
+            raise ExtractionFailure("no extractable text")
+        if proc.returncode != 0:
+            tail = _stderr_tail(stderr_path) or f"exit code {proc.returncode}"
+            raise ExtractionFailure(f"parser failed: {tail}")
+
+        if out_json.stat().st_size > MAX_EXTRACTION_JSON_BYTES:
+            raise ExtractionFailure("extraction output too large")
+        data = json.loads(out_json.read_text())
+        return Extraction(pages=data["pages"], chunks=[ChunkData(**c) for c in data["chunks"]])

groundly/ingestion/extract_worker.py

@@ -0,0 +1,126 @@
+"""Extraction worker — runs as `python -m groundly.ingestion.extract_worker <in> <out.json>`.
+
+Always a child process: a parser crash on a hostile/broken file kills this process,
+not the indexing run (UC-01 A2, security.md §3). Digital documents only — no OCR;
+an empty text layer exits with EXIT_NO_TEXT so the parent reports the specific cause.
+A model that can't be loaded (uncached + offline, HF rate-limit, missing dep) exits
+with EXIT_MODEL_UNAVAILABLE — an environment failure, retryable, never a bad document.
+
+Output JSON: {"pages": N|null, "chunks": [{"text", "heading_path", "page", "token_count"}]}
+"""
+
+import json
+import sys
+from pathlib import Path
+
+EXIT_NO_TEXT = 3
+EXIT_MODEL_UNAVAILABLE = 4
+
+DOCLING_SUFFIXES = {".pdf", ".docx", ".pptx", ".md"}
+# Everything else on the pipeline allowlist (txt + source code) is read as plain
+# text and chunked by token windows — docling's converter does not accept it.
+
+
+def _bge_m3_tokenizer():
+    from transformers import AutoTokenizer
+
+    from groundly.core.manifest import EMBEDDING_MODEL, HF_REVISION
+
+    return AutoTokenizer.from_pretrained(EMBEDDING_MODEL, revision=HF_REVISION)
+
+
+def _model_step(fn):
+    """Model loading is the network/dependency-bound step. A failure (uncached + offline,
+    HF rate-limit, missing dep) is transient — the parent retries it — so it exits
+    distinctly, never collapsing into a terminal 'bad document'."""
+    try:
+        return fn()
+    except Exception as exc:
+        print(f"model unavailable: {exc}", file=sys.stderr)
+        sys.exit(EXIT_MODEL_UNAVAILABLE)
+
+
+def _extract_docling(path: Path) -> dict:
+    from docling.chunking import HybridChunker
+    from docling.datamodel.base_models import InputFormat
+    from docling.document_converter import DocumentConverter
+    from docling_core.transforms.chunker.tokenizer.huggingface import HuggingFaceTokenizer
+
+    from groundly.core.manifest import CHUNK_MAX_TOKENS
+
+    formats = {
+        ".pdf": InputFormat.PDF,
+        ".docx": InputFormat.DOCX,
+        ".pptx": InputFormat.PPTX,
+        ".md": InputFormat.MD,
+    }
+    converter = DocumentConverter()
+    # docling's layout models load here, before the document is touched — a fetch
+    # failure is the environment's fault, never this document's parse failure
+    _model_step(lambda: converter.initialize_pipeline(formats[path.suffix.lower()]))
+    doc = converter.convert(path).document
+    tokenizer = HuggingFaceTokenizer(
+        tokenizer=_model_step(_bge_m3_tokenizer), max_tokens=CHUNK_MAX_TOKENS
+    )
+    chunker = HybridChunker(tokenizer=tokenizer, merge_peers=True)
+
+    chunks = []
+    for chunk in chunker.chunk(doc):
+        text = chunker.contextualize(chunk)  # heading path prepended — what gets embedded
+        headings = getattr(chunk.meta, "headings", None) or []
+        page = None
+        for item in getattr(chunk.meta, "doc_items", []) or []:
+            prov = getattr(item, "prov", None)
+            if prov:
+                page = prov[0].page_no
+                break
+        chunks.append(
+            {
+                "text": text,
+                "heading_path": " > ".join(headings) or None,
+                "page": page,
+                "token_count": tokenizer.count_tokens(text),
+            }
+        )
+
+    pages = len(doc.pages) if doc.pages else None
+    return {"pages": pages, "chunks": chunks}
+
+
+def _extract_plain_text(path: Path) -> dict:
+    from groundly.core.manifest import CHUNK_MAX_TOKENS
+
+    text = path.read_text(errors="replace")
+    tokenizer = _model_step(_bge_m3_tokenizer)
+    ids = tokenizer.encode(text, add_special_tokens=False)
+    chunks = []
+    for start in range(0, len(ids), CHUNK_MAX_TOKENS):
+        window = ids[start : start + CHUNK_MAX_TOKENS]
+        chunks.append(
+            {
+                "text": tokenizer.decode(window),
+                "heading_path": None,
+                "page": None,
+                "token_count": len(window),
+            }
+        )
+    return {"pages": None, "chunks": chunks}
+
+
+def main() -> None:
+    in_path, out_path = Path(sys.argv[1]), Path(sys.argv[2])
+
+    if in_path.suffix.lower() in DOCLING_SUFFIXES:
+        result = _extract_docling(in_path)
+    else:
+        result = _extract_plain_text(in_path)
+
+    if not any(c["text"].strip() for c in result["chunks"]):
+        # digital-documents-only rule (pivot #3): empty text layer, no OCR fallback
+        sys.exit(EXIT_NO_TEXT)
+
+    out_path.write_text(json.dumps(result))
+
+
+if __name__ == "__main__":
+    main()

groundly/ingestion/pipeline.py

@@ -0,0 +1,210 @@
+"""The index pipeline (UC-01): hash-skip idempotent, per-file transactions, the run
+continues past failures. Ingestion writes the stores; it never serves queries."""
+
+import hashlib
+import shutil
+import sqlite3
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+import sqlite_vec
+
+from groundly.core import store
+from groundly.core.manifest import sync_counts
+from groundly.core.paths import subject_dir
+from groundly.ingestion.extract import ExtractionFailure, ModelUnavailable, extract
+from groundly.llm.embeddings import BgeM3Embedder, Embedder
+
+SUPPORTED_SUFFIXES = {
+    ".pdf",
+    ".docx",
+    ".pptx",
+    ".txt",
+    ".md",
+    ".py",
+    ".c",
+    ".cpp",
+    ".h",
+    ".hpp",
+    ".java",
+    ".js",
+    ".ts",
+    ".rs",
+    ".go",
+}
+
+# FileResult.status values
+INDEXED = "indexed"
+SKIPPED_DUPLICATE = "skipped_duplicate"
+SKIPPED_UNSUPPORTED = "skipped_unsupported"
+SKIPPED_FAILED = "skipped_failed"  # failed on an earlier run; `remove` it to retry
+EXTRACTION_FAILED = "extraction_failed"  # terminal, recorded in store.db
+ERROR = "error"  # transient (e.g. embedder crash), no row recorded
+
+OnEvent = Callable[[Path, str], None]
+
+
+@dataclass
+class FileResult:
+    path: Path
+    status: str
+    detail: str | None = None
+    chunks: int = 0
+
+
+def _iter_files(paths: list[Path]) -> list[Path]:
+    files: list[Path] = []
+    for p in paths:
+        if p.is_dir():
+            files.extend(sorted(f for f in p.rglob("*") if f.is_file()))
+        else:
+            files.append(p)
+    return files
+
+
+def _sha256(path: Path) -> str:
+    with open(path, "rb") as f:
+        return hashlib.file_digest(f, "sha256").hexdigest()
+
+
+def _copy_to_materials(src: Path, sha256: str, materials_dir: Path) -> str:
+    """Original files are the citation targets; they ship in exports."""
+    dest = materials_dir / src.name
+    if dest.exists():
+        if dest.samefile(src):  # orphan already in materials/ — or a hard link to it
+            return dest.name
+        if _sha256(dest) != sha256:
+            dest = materials_dir / f"{src.stem}-{sha256[:8]}{src.suffix}"
+    shutil.copy2(src, dest)
+    return dest.name
+
+
+def index_paths(
+    subject: str,
+    paths: list[Path],
+    embedder: Embedder | None = None,
+    on_event: OnEvent | None = None,
+) -> list[FileResult]:
+    sdir = subject_dir(subject)
+    manifest_path = sdir / "manifest.json"
+    if not manifest_path.exists():
+        raise RuntimeError(f"subject '{subject}' is not initialized — run: groundly init {subject}")
+
+    emit = on_event or (lambda path, stage: None)
+    embedder = embedder or BgeM3Embedder()
+    results: list[FileResult] = []
+    conn = store.connect(sdir / "store.db")
+    try:
+        known = store.hash_status(conn)
+        for path in _iter_files(paths):
+            emit(path, "queued")
+            if path.is_symlink():  # a hostile symlink would index (and later export)
+                results.append(FileResult(path, SKIPPED_UNSUPPORTED, "symlink — not followed"))
+                emit(path, SKIPPED_UNSUPPORTED)
+                continue
+            if not path.exists():
+                results.append(FileResult(path, ERROR, "file not found"))
+                emit(path, ERROR)
+                continue
+            if path.suffix.lower() not in SUPPORTED_SUFFIXES:
+                results.append(
+                    FileResult(path, SKIPPED_UNSUPPORTED, f"unsupported type {path.suffix!r}")
+                )
+                emit(path, SKIPPED_UNSUPPORTED)
+                continue
+
+            sha = _sha256(path)
+            if known.get(sha) == "indexed":
+                results.append(FileResult(path, SKIPPED_DUPLICATE, "already indexed"))
+                emit(path, SKIPPED_DUPLICATE)
+                continue
+            if known.get(sha) == "extraction_failed":
+                # terminal per UC-01: don't re-extract every run; `remove` it to retry
+                error = store.find_materials(conn, sha)[0]["error"]
+                results.append(
+                    FileResult(
+                        path, SKIPPED_FAILED, f"failed previously: {error} — remove to retry"
+                    )
+                )
+                emit(path, SKIPPED_FAILED)
+                continue
+
+            result = _index_one(conn, path, sha, sdir, embedder, emit)
+            results.append(result)
+            if result.status in (INDEXED, EXTRACTION_FAILED):
+                known[sha] = result.status  # a same-content sibling this run is a skip
+            sync_counts(conn, manifest_path)
+    finally:
+        conn.close()
+    return results
+
+
+def _index_one(
+    conn, path: Path, sha: str, sdir: Path, embedder: Embedder, emit: OnEvent
+) -> FileResult:
+    emit(path, "extracting")
+    try:
+        extraction = extract(path)
+    except ModelUnavailable as exc:  # transient (offline/uncached model): no row, next run retries
+        emit(path, ERROR)
+        return FileResult(path, ERROR, f"extractor unavailable: {exc}")
+    except ExtractionFailure as failure:
+        try:
+            with conn:
+                conn.execute(
+                    "INSERT INTO materials (filename, sha256, status, error) "
+                    "VALUES (?, ?, 'extraction_failed', ?)",
+                    (path.name, sha, str(failure)),
+                )
+        except sqlite3.IntegrityError:
+            pass  # sha256 UNIQUE lost a race: a concurrent run recorded this content first
+        emit(path, EXTRACTION_FAILED)
+        return FileResult(path, EXTRACTION_FAILED, str(failure))
+
+    emit(path, "embedding")
+    try:
+        dense, sparse = embedder.encode([c.text for c in extraction.chunks])
+    except Exception as exc:  # transient (model load/OOM): no row, next run retries
+        emit(path, ERROR)
+        return FileResult(path, ERROR, f"embedding failed: {exc}")
+
+    try:
+        stored_name = _copy_to_materials(path, sha, sdir / "materials")
+    except OSError as exc:  # transient (disk full, permissions): no row, next run retries
+        emit(path, ERROR)
+        return FileResult(path, ERROR, f"copy to materials failed: {exc}")
+    try:
+        return _write_indexed(conn, path, sha, stored_name, extraction, dense, sparse, emit)
+    except sqlite3.IntegrityError:
+        # sha256 UNIQUE lost a race: a concurrent run (CLI + MCP share the store)
+        # indexed the same content between our hash check and this write
+        emit(path, SKIPPED_DUPLICATE)
+        return FileResult(path, SKIPPED_DUPLICATE, "already indexed (concurrent run)")
+
+
+def _write_indexed(
+    conn, path: Path, sha: str, stored_name: str, extraction, dense, sparse, emit: OnEvent
+) -> FileResult:
+    with conn:  # one transaction per file: Ctrl-C loses at most the in-flight file
+        cur = conn.execute(
+            "INSERT INTO materials (filename, sha256, status, pages) VALUES (?, ?, 'indexed', ?)",
+            (stored_name, sha, extraction.pages),
+        )
+        material_id = cur.lastrowid
+        for chunk, vec, weights in zip(extraction.chunks, dense, sparse, strict=True):
+            cid = conn.execute(
+                "INSERT INTO chunks (material_id, page, heading_path, text, token_count) "
+                "VALUES (?, ?, ?, ?, ?)",
+                (material_id, chunk.page, chunk.heading_path, chunk.text, chunk.token_count),
+            ).lastrowid
+            conn.execute(
+                "INSERT INTO vectors (rowid, embedding) VALUES (?, ?)",
+                (cid, sqlite_vec.serialize_float32(vec)),
+            )
+            conn.executemany(
+                "INSERT INTO sparse_terms (token_id, chunk_id, weight) VALUES (?, ?, ?)",
+                [(token_id, cid, weight) for token_id, weight in weights.items()],
+            )
+    emit(path, INDEXED)
+    return FileResult(path, INDEXED, chunks=len(extraction.chunks))

groundly/llm/embeddings.py

@@ -0,0 +1,62 @@
+"""bge-m3 embedding: dense (1024-d, normalized) + learned sparse from one forward pass.
+
+Lives in llm/ because embedding clients are constructed only here (overview.md module
+rules); it is local and key-free, so no cost metering applies. Lazy-loaded — never at
+import/spawn time (.claude/rules/architecture.md). The model is
+resolved at the pinned hf_revision via snapshot_download, which is the interchange
+compatibility contract: same pin ⇒ shared vectors transfer as-is.
+"""
+
+import sys
+from typing import Protocol
+
+from groundly.core.manifest import EMBEDDING_MODEL, HF_REVISION
+
+SparseWeights = dict[int, float]
+
+
+class Embedder(Protocol):
+    def encode(self, texts: list[str]) -> tuple[list[list[float]], list[SparseWeights]]: ...
+
+
+class BgeM3Embedder:
+    def __init__(self) -> None:
+        self._model = None
+
+    def _load(self):
+        if self._model is None:
+            from pathlib import Path
+
+            from huggingface_hub import snapshot_download
+
+            try:
+                # a snapshot can exist with only tokenizer files (the extraction
+                # worker caches those) — "cached" means the weights are present
+                local = snapshot_download(
+                    EMBEDDING_MODEL, revision=HF_REVISION, local_files_only=True
+                )
+                if not any(
+                    (Path(local) / name).exists()
+                    for name in ("model.safetensors", "pytorch_model.bin")
+                ):
+                    raise FileNotFoundError("model weights not cached")
+            except Exception:
+                print(
+                    f"downloading {EMBEDDING_MODEL} (one-time, ~2.3 GB) …",
+                    file=sys.stderr,
+                )
+                local = snapshot_download(EMBEDDING_MODEL, revision=HF_REVISION)
+
+            from FlagEmbedding import BGEM3FlagModel
+
+            self._model = BGEM3FlagModel(local, use_fp16=False)
+        return self._model
+
+    def encode(self, texts: list[str]) -> tuple[list[list[float]], list[SparseWeights]]:
+        out = self._load().encode(texts, return_dense=True, return_sparse=True)
+        dense = [vec.tolist() for vec in out["dense_vecs"]]
+        sparse = [
+            {int(token_id): float(weight) for token_id, weight in weights.items()}
+            for weights in out["lexical_weights"]
+        ]
+        return dense, sparse

groundly/web/static/theme.css

@@ -0,0 +1,22 @@
+:root {
+	--bg: #111318;
+	--surface: #1a1c20;
+	--primary: #c5c0ff;
+	--primary-contrast: #2a2179;
+	--button-primary: #2f277e;
+	--button-primary-hover: #413a91;
+	--secondary: #89ceff;
+	--secondary-contrast: #00344d;
+	--error: #ffb4ab;
+	--success: #6ee7b7;
+	--warning: #fcd34d;
+	--text: #e2e2e8;
+	--text-secondary: #c8c4d3;
+	--divider: #474551;
+
+	--font-body: "Inter", system-ui, sans-serif;
+	--font-heading: "Source Serif 4", Georgia, serif;
+	--font-mono: "JetBrains Mono", monospace;
+	--radius: 4px;
+	--radius-card: 8px;
+}

groundly-0.3.0.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: groundly
+Version: 0.3.0
+Summary: Local-first course knowledge bases for AI agents: index your materials, study grounded, share the index.
+License: MIT License
+        
+        Copyright (c) 2026 Paul Hondola
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: <3.13,>=3.11
+Requires-Dist: docling==2.113.0
+Requires-Dist: fastapi>=0.111
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: flagembedding==1.3.5
+Requires-Dist: genanki>=0.13
+Requires-Dist: graphrag==3.1.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: llama-index==0.14.23
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: pydantic>=2.7
+Requires-Dist: rich>=13
+Requires-Dist: sentence-transformers==5.6.0
+Requires-Dist: sqlite-vec>=0.1
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: eval
+Requires-Dist: ragas>=0.2; extra == 'eval'
+Description-Content-Type: text/markdown
+
+# Groundly
+
+**Local-first course knowledge bases for AI agents.** Index your course materials once; then any MCP-capable agent — Claude Code, Claude Desktop, Codex — can answer questions grounded in the actual course content with page-level citations, generate execution-verified tests and flashcards, quiz your weak areas, and track your mastery. Share the finished knowledge base with your coursemates as a single file.
+
+Bachelor thesis project, Universitatea Politehnica Timișoara.
+
+```
+$ groundly index <SUBJECT> ./slides/
+  ✓ 12 PDFs → 384 chunks → embedded (bge-m3, local) → indexed
+$ # wire into Claude Code:  { "command": "groundly", "args": ["mcp"] }
+```
+
+Then, inside your agent: *"What did lecture 4 say about deadlock prevention?"* → answer cited to **lecture-04.pdf, page 12, "Deadlocks › Prevention"** — or *"not covered by the course materials"*, never a hallucination.
+
+## Why not NotebookLM / a Claude Project?
+
+1. **Verified generation** — every test question and flashcard passes a verifier: answerable from the cited sources, answer key checked, and code questions' reference solutions **actually executed** before acceptance.
+2. **Enforced citations** — structural, page-level, with honest refusal when the corpus doesn't cover it.
+3. **A portable index** — `groundly export <SUBJECT>` → one file; a coursemate imports it and their agent uses it directly. The expensive artifacts (knowledge graph, verified decks) are built once and shared.
+4. **Cross-host progress** — mastery per topic and study memory persist in local files, whatever agent you talk to. Your queries and results never leave your machine and are never part of an export.
+
+## Features
+
+- **Grounded Q&A** — hybrid retrieval (bge-m3 dense + learned sparse + BM25, reranked; optional GraphRAG for synthesis questions), via MCP tools or `groundly ask`
+- **Verified quizzes & coding challenges** — generated by Groundly (your API key) *or by your agent* (no key needed) — either way, nothing unverified is stored
+- **Flashcards → Anki** — verified decks exported as `.apkg`
+- **Mastery map & study memory** — per-topic mastery from quiz results; "continue studying" warm starts in any host
+- **Import/export** — the whole knowledge base as one shareable file, with pinned-model compatibility
+
+## Install
+
+```
+uv tool install groundly
+```
+
+Local-first honestly stated: first run downloads the embedding models (~2.7GB total). Indexing and search need **no API key**; grounded answer generation and graph builds use your own OpenAI-compatible provider (cloud key, LM Studio, or Ollama).
+
+**Thesis core:** four-arm RAG vs GraphRAG evaluation on real RO/EN course corpora, plus a measured comparison of enforced vs agent-mediated grounding.

groundly-0.3.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+groundly/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+groundly/agents/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+groundly/cli/__init__.py,sha256=sbtFMmcGY_m4-yGRYZhNUFoBvVtZcfHSP4yVWDvVe2w,9173
+groundly/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+groundly/core/manifest.py,sha256=u-wR8MNP1enbbFfmFegxY2-NUBpbegDDUPetHJf9vR4,2380
+groundly/core/paths.py,sha256=H5RGprGcNNdi-a3cOUVyUFBpczYZjk97YsvzHD77YeE,1026
+groundly/core/store.py,sha256=rJUtqkaIQteMoGuwFcToLDRB3C84X-Zqdp4M5deNmlg,5328
+groundly/core/subject.py,sha256=ZwdH_Imwx6u3VVMxhLwol8k-BntB4hC59Da6OgAj328,1539
+groundly/ingestion/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+groundly/ingestion/extract.py,sha256=of6jCglIgeax8WhB7oWmRYaga-bxr-mBrJEslL7JbeI,3352
+groundly/ingestion/extract_worker.py,sha256=-GDY_FYuYO7GTBVoIkXIhcpQHACi40NXkuM5j93vSO0,4516
+groundly/ingestion/pipeline.py,sha256=lMfvtMgvwFajvFEZeAjD9vu3aNZrdFUYBHAKofbvV80,7809
+groundly/llm/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+groundly/llm/embeddings.py,sha256=uWT5zm9Jo80b9FEr7vlHidbewDpwSNEUghJ3D6WF7Jc,2375
+groundly/mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+groundly/retrieval/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+groundly/web/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+groundly/web/static/theme.css,sha256=4e8rbyAy5RAkNURj48CVB30xppu1rZWC0-mi5Ldg9Ls,521
+groundly-0.3.0.dist-info/METADATA,sha256=Q27eYKckOwuMt5ry0r0aTxC3g4oHKwZvcE8aAb5YdTI,4951
+groundly-0.3.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+groundly-0.3.0.dist-info/entry_points.txt,sha256=blWT1cwUIOmqI_YrHRbAt_mJdYMm0fPKH9Wj5QJs59c,46
+groundly-0.3.0.dist-info/licenses/LICENSE,sha256=lCwN0jTaLVFgdybko2FT6i7jjLrhHYwedxP3s6wQSj0,1069
+groundly-0.3.0.dist-info/RECORD,,

groundly-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

groundly-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+groundly = groundly.cli:app

groundly-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Hondola
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.