loom-data 0.1.0__py3-none-any.whl

loom/__init__.py

@@ -0,0 +1,16 @@
+from .chat import LoomCommandRequest, ScanRequest, is_fast_scan_command, parse_chat_request, parse_loom_command
+from .data import get, pull
+from .scanner import ScanResult, scan_topic_from_chat, scan_topic_to_explore
+
+__all__ = [
+    "LoomCommandRequest",
+    "ScanRequest",
+    "ScanResult",
+    "get",
+    "is_fast_scan_command",
+    "parse_chat_request",
+    "parse_loom_command",
+    "pull",
+    "scan_topic_from_chat",
+    "scan_topic_to_explore",
+]

loom/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

loom/chat.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re
+
+
+@dataclass(frozen=True)
+class LoomCommandRequest:
+    command: str
+    workspace: str | None
+    original_message: str
+
+
+@dataclass(frozen=True)
+class ScanRequest:
+    topic: str
+    original_message: str
+
+
+_WORKSPACE_PATTERN = r"[a-z0-9][a-z0-9_./-]*"
+_SCAN_PATTERNS = (
+    re.compile(rf"(?i)(?:^|\b)loom\s+scan\s+(?P<workspace>{_WORKSPACE_PATTERN})\b"),
+    re.compile(rf"(?i)(?:^|\b)(?:please\s+)?scan\s+(?P<workspace>{_WORKSPACE_PATTERN})\s+with\s+loom\b"),
+)
+_GENERIC_PATTERNS = (
+    re.compile(rf"(?i)(?:^|\b)loom\s+(?P<command>confirm|push|pull|status)(?:\s+(?P<workspace>{_WORKSPACE_PATTERN}))?\b"),
+)
+
+
+def is_fast_scan_command(message: str) -> bool:
+    normalized = message.strip()
+    if not normalized:
+        return False
+
+    lowered = normalized.lower()
+    return lowered.startswith("loom scan ") and len(normalized) > len("loom scan ")
+
+
+def parse_chat_request(message: str) -> ScanRequest | None:
+    command_request = parse_loom_command(message)
+    if command_request is None or command_request.command != "scan" or command_request.workspace is None:
+        return None
+    return ScanRequest(topic=command_request.workspace, original_message=message)
+
+
+def parse_loom_command(message: str) -> LoomCommandRequest | None:
+    normalized = message.strip()
+    if not normalized:
+        return None
+
+    fast_request = _parse_fast_scan_command(normalized, message)
+    if fast_request is not None:
+        return fast_request
+
+    for pattern in _SCAN_PATTERNS:
+        match = pattern.search(normalized)
+        if match:
+            return LoomCommandRequest(
+                command="scan",
+                workspace=_normalize_workspace(match.group("workspace")),
+                original_message=message,
+            )
+
+    for pattern in _GENERIC_PATTERNS:
+        match = pattern.search(normalized)
+        if match:
+            return LoomCommandRequest(
+                command=match.group("command").lower(),
+                workspace=_normalize_workspace(match.group("workspace")),
+                original_message=message,
+            )
+
+    return None
+
+
+def _parse_fast_scan_command(normalized: str, original_message: str) -> LoomCommandRequest | None:
+    parts = normalized.split(None, 2)
+    if len(parts) < 3:
+        return None
+
+    if parts[0].lower() != "loom" or parts[1].lower() != "scan":
+        return None
+
+    workspace = parts[2].strip().strip("/").split()[0]
+    if not re.fullmatch(_WORKSPACE_PATTERN, workspace, flags=re.IGNORECASE):
+        return None
+
+    return LoomCommandRequest(command="scan", workspace=workspace, original_message=original_message)
+
+
+def _normalize_workspace(value: str | None) -> str | None:
+    if value is None:
+        return None
+    return value.strip().strip("/") or None

loom/cli.py

@@ -0,0 +1,4 @@
+from .cli_app import main
+from .cli_app.config import DEFAULT_DATABASE_URL
+
+__all__ = ["DEFAULT_DATABASE_URL", "main"]

loom/cli_app/__init__.py

@@ -0,0 +1,3 @@
+from .main import main
+
+__all__ = ["main"]

loom/cli_app/config.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+import os
+
+
+DEFAULT_SERVER_URL = os.environ.get("LOOM_SERVER_URL", "http://127.0.0.1:8765")
+DEFAULT_DATABASE_URL = os.environ.get(
+    "LOOM_SERVER_DATABASE_URL",
+    "postgresql+psycopg2://loom@127.0.0.1:5432/loom",
+)

loom/cli_app/handlers.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import argparse
+
+from ..data import get as get_resource
+from ..explore_repo import confirm_changes, ensure_explore_repo
+from ..scanner import scan_topic_to_explore
+from ..sync_client import pull_raw_workspaces, pull_workspaces, push_workspaces
+from .output import print_status_summary, print_workspace_status
+from .skill import install_skill
+
+
+def run_install(args: argparse.Namespace) -> int:
+    skill_dir = install_skill(args.codex_home.resolve(), args.workspace_root.resolve())
+    repo_dir = ensure_explore_repo(args.workspace_root.resolve())
+    print(f"Installed Loom scan skill to: {skill_dir}")
+    print(f"Initialized loom_explore git repo at: {repo_dir}")
+    print("Codex can now use a fast path for chat messages like `loom scan energy`.")
+    return 0
+
+
+def run_scan(args: argparse.Namespace) -> int:
+    result = scan_topic_to_explore(args.topic, args.workspace_root)
+    print(f"Scanned topic: {result.topic}")
+    print(f"Raw directory: {result.raw_topic_dir}")
+    print(f"Explore directory: {result.explore_topic_dir}")
+    print(f"Datasets discovered: {result.dataset_count}")
+    print(f"Datasets rebuilt: {len(result.rebuilt_dataset_dirs)}")
+    for dataset_dir in result.rebuilt_dataset_dirs:
+        print(f"- rebuilt: {dataset_dir}")
+    print(f"Datasets skipped: {len(result.skipped_dataset_dirs)}")
+    for dataset_dir in result.skipped_dataset_dirs:
+        print(f"- skipped: {dataset_dir}")
+    if result.missing_dataset_dirs:
+        print(f"Missing source datasets kept in explore: {len(result.missing_dataset_dirs)}")
+        for relative_dir in result.missing_dataset_dirs:
+            print(f"- kept: {relative_dir}")
+    print_status_summary(args.workspace_root, args.topic)
+    return 0
+
+
+def run_get(args: argparse.Namespace) -> int:
+    local_path = get_resource(args.resource, workspace_root=args.workspace_root, server_url=args.server_url)
+    print(f"Cached resource: {args.resource}")
+    print(f"Local path: {local_path}")
+    return 0
+
+
+def run_status(args: argparse.Namespace) -> int:
+    print_workspace_status(args.workspace_root, args.workspace)
+    return 0
+
+
+def run_confirm(args: argparse.Namespace) -> int:
+    commit_hash = confirm_changes(args.workspace_root, args.workspace, getattr(args, "message", None))
+    if commit_hash is None:
+        print("No pending changes to confirm.")
+        return 0
+    print(f"Confirmed changes for {args.workspace or 'all workspaces'}.")
+    print(f"Commit: {commit_hash}")
+    return 0
+
+
+def run_push(args: argparse.Namespace) -> int:
+    return _print_push_results(push_workspaces(args.workspace_root, args.server_url, args.workspace, args.message))
+
+
+def run_pull(args: argparse.Namespace) -> int:
+    return _print_pull_results(pull_workspaces(args.workspace_root, args.server_url, args.workspace))
+
+
+def run_pull_raw(args: argparse.Namespace) -> int:
+    results = pull_raw_workspaces(args.workspace_root, args.server_url, args.workspace)
+    if not results:
+        print("No remote workspaces found to pull raw files for.")
+        return 0
+    for result in results:
+        print(f"Pulled raw workspace: {result.workspace}")
+        print(f"Manifest files: {result.manifest_file_count}")
+        print(f"Downloaded files: {result.downloaded_file_count}")
+        print(f"Linked local files: {result.linked_file_count}")
+        print(f"Deleted files: {result.deleted_file_count}")
+        if result.raw_conflict_notice_path:
+            print(f"Raw conflict notice: {result.raw_conflict_notice_path}")
+    return 0
+
+
+def _print_push_results(results: tuple[object, ...]) -> int:
+    if not results:
+        print("No local workspaces found to push.")
+        return 0
+    exit_code = 0
+    for result in results:
+        if result.conflicted:
+            exit_code = 1
+            print(f"Push paused for workspace: {result.workspace}")
+            print(f"Remote revision: {result.revision_id or '-'}")
+            print("Conflict detected during rebase. Resolve the files below, then run:")
+            print(f"  loom confirm {result.workspace}")
+            print(f"  loom push {result.workspace}")
+            for path in result.conflict_paths:
+                print(f"- conflict: {path}")
+            continue
+        print(f"Pushed workspace: {result.workspace}")
+        print(f"Revision: {result.revision_id}")
+        print(f"Tree hash: {result.tree_hash}")
+        print(f"Changed files: {result.changed_file_count}")
+        print(f"Deleted files: {result.deleted_file_count}")
+        print(f"Raw objects uploaded: {result.raw_uploaded_object_count}")
+        print(f"Raw path mappings changed: {result.raw_mapping_changed_count}")
+        print(f"Raw path mappings deleted: {result.raw_mapping_deleted_count}")
+        if result.raw_conflict_notice_path:
+            print(f"Raw conflict notice: {result.raw_conflict_notice_path}")
+    return exit_code
+
+
+def _print_pull_results(results: tuple[object, ...]) -> int:
+    if not results:
+        print("No remote workspaces found to pull.")
+        return 0
+    exit_code = 0
+    for result in results:
+        print(f"Pulled workspace: {result.workspace}")
+        print(f"Revision: {result.revision_id}")
+        print(f"Changed: {'yes' if result.changed else 'no'}")
+        print(f"Changed files: {result.changed_file_count}")
+        print(f"Deleted files: {result.deleted_file_count}")
+        if result.conflicted:
+            exit_code = 1
+            print("Conflict detected during rebase. Resolve the files below, then run:")
+            print(f"  loom confirm {result.workspace}")
+            print(f"  loom push {result.workspace}")
+            for path in result.conflict_paths:
+                print(f"- conflict: {path}")
+        elif result.raw_conflict_notice_path:
+            print(f"Raw conflict notice: {result.raw_conflict_notice_path}")
+    return exit_code

loom/cli_app/main.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import importlib
+import sys
+
+from .handlers import run_confirm, run_get, run_install, run_pull, run_pull_raw, run_push, run_scan, run_status
+from .parser import build_parser
+from .routing import run_route
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    handlers = {
+        "install": run_install,
+        "scan": run_scan,
+        "route": run_route,
+        "get": run_get,
+        "status": run_status,
+        "confirm": run_confirm,
+        "push": run_push,
+        "pull": run_pull,
+        "pull-raw": run_pull_raw,
+    }
+    if args.command in handlers:
+        return handlers[args.command](args)
+    if args.command == "server-init-db":
+        return _run_server_command("run_init_db", args.database_url, args.storage_root)
+    if args.command == "server-run":
+        return _run_server_command("run_server", args.database_url, args.storage_root, args.host, args.port)
+    build_parser().print_help()
+    return 1
+
+
+def _run_server_command(function_name: str, *args: object) -> int:
+    try:
+        module = importlib.import_module("loom_server.cli")
+    except ModuleNotFoundError as exc:
+        if exc.name == "loom_server":
+            print(
+                "This command requires the separate 'loom-server' package. "
+                "Install it first, then rerun the command.",
+                file=sys.stderr,
+            )
+            return 1
+        raise
+
+    command = getattr(module, function_name)
+    return int(command(*args))

loom/cli_app/output.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..explore_repo import get_repo_status
+from ..sync_state import load_workspace_sync_state
+
+
+def print_status_summary(workspace_root: Path | str, workspace: str) -> None:
+    status = get_repo_status(workspace_root, workspace)
+    if not status.entries:
+        print("No pending changes detected after scan.")
+        return
+    launcher = Path(workspace_root).resolve() / "scripts" / "loom.py"
+    print("Pending changes:")
+    for entry in status.entries:
+        print(f"{entry.code} {entry.path}")
+    print(f"Confirm with: uv run python {launcher} confirm {workspace}")
+
+
+def print_workspace_status(workspace_root: Path | str, workspace: str | None) -> None:
+    status = get_repo_status(workspace_root, workspace)
+    print(f"Explore repo: {status.repo_dir}")
+    if status.scope:
+        state = load_workspace_sync_state(workspace_root, status.scope)
+        print(f"Workspace: {status.scope}")
+        print(f"Last pulled revision: {state.last_pulled_revision or '-'}")
+        print(f"Last pushed revision: {state.last_pushed_revision or '-'}")
+        print(f"Last synced tree hash: {state.last_synced_tree_hash or '-'}")
+        print(f"Last sync commit: {state.last_sync_commit or '-'}")
+        if state.pending_rebase_revision:
+            print(f"Pending rebase revision: {state.pending_rebase_revision}")
+    if not status.entries:
+        print("No pending changes.")
+        return
+    print("Pending changes:")
+    for entry in status.entries:
+        print(f"{entry.code} {entry.path}")

loom/cli_app/parser.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+from .config import DEFAULT_DATABASE_URL, DEFAULT_SERVER_URL
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="loom")
+    subparsers = parser.add_subparsers(dest="command")
+    _add_install_parser(subparsers)
+    _add_scan_parsers(subparsers)
+    _add_data_parsers(subparsers)
+    _add_sync_parsers(subparsers)
+    return parser
+
+
+def _add_install_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    install_parser = subparsers.add_parser("install", help="Install the Loom Codex skill and initialize loom_explore git tracking.")
+    install_parser.add_argument("--codex-home", type=Path, default=Path(os.environ.get("CODEX_HOME", Path.home() / ".codex")))
+    install_parser.add_argument("--workspace-root", type=Path, default=Path.cwd())
+
+
+def _add_scan_parsers(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    scan_parser = subparsers.add_parser("scan", help="Scan a Loom topic from loom_raw into loom_explore.")
+    scan_parser.add_argument("topic")
+    scan_parser.add_argument("--workspace-root", type=Path, default=Path.cwd())
+
+    route_parser = subparsers.add_parser("route", help="Parse a chat message and run loom scan if it matches.")
+    route_parser.add_argument("message")
+    route_parser.add_argument("--workspace-root", type=Path, default=Path.cwd())
+
+
+def _add_data_parsers(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    get_parser = subparsers.add_parser("get", help="Ensure one raw file exists under test-project/loom/.loom/raw and print its local path.")
+    get_parser.add_argument("resource")
+    get_parser.add_argument("--server-url", default=DEFAULT_SERVER_URL)
+    get_parser.add_argument("--workspace-root", type=Path, default=Path.cwd())
+
+    pull_raw_parser = subparsers.add_parser("pull-raw", help="Pull latest raw files into test-project/loom/.loom/raw.")
+    pull_raw_parser.add_argument("workspace", nargs="?")
+    pull_raw_parser.add_argument("--server-url", default=DEFAULT_SERVER_URL)
+    pull_raw_parser.add_argument("--workspace-root", type=Path, default=Path.cwd())
+
+
+def _add_sync_parsers(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    _add_workspace_parser(subparsers, "status", "Show pending loom_explore changes.", include_message=False)
+    _add_workspace_parser(subparsers, "confirm", "Commit pending loom_explore changes.", include_message=True)
+    _add_workspace_parser(subparsers, "push", "Push local workspaces to the Loom sync server.", include_message=True, include_server=True)
+    _add_workspace_parser(subparsers, "pull", "Pull remote workspaces from the Loom sync server.", include_server=True)
+
+    init_parser = subparsers.add_parser("server-init-db", help="Initialize the Loom sync server database schema.")
+    init_parser.add_argument("--database-url", default=DEFAULT_DATABASE_URL)
+    init_parser.add_argument("--storage-root", type=Path, default=Path(os.environ.get("LOOM_SERVER_STORAGE_ROOT", Path.cwd() / ".loom-server-storage")))
+
+    run_parser = subparsers.add_parser("server-run", help="Run the Loom sync FastAPI server.")
+    run_parser.add_argument("--database-url", default=DEFAULT_DATABASE_URL)
+    run_parser.add_argument("--storage-root", type=Path, default=Path(os.environ.get("LOOM_SERVER_STORAGE_ROOT", Path.cwd() / ".loom-server-storage")))
+    run_parser.add_argument("--host", default="127.0.0.1")
+    run_parser.add_argument("--port", type=int, default=8765)
+
+
+def _add_workspace_parser(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+    name: str,
+    help_text: str,
+    *,
+    include_message: bool = False,
+    include_server: bool = False,
+) -> None:
+    parser = subparsers.add_parser(name, help=help_text)
+    parser.add_argument("workspace", nargs="?")
+    if include_message:
+        parser.add_argument("--message")
+    if include_server:
+        parser.add_argument("--server-url", default=DEFAULT_SERVER_URL)
+    parser.add_argument("--workspace-root", type=Path, default=Path.cwd())

loom/cli_app/routing.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import argparse
+
+from ..chat import parse_loom_command
+from ..scanner import scan_topic_from_chat
+from .config import DEFAULT_SERVER_URL
+from .handlers import run_confirm, run_pull, run_push, run_status
+from .output import print_status_summary
+
+
+def run_route(args: argparse.Namespace) -> int:
+    request = parse_loom_command(args.message)
+    if request is None:
+        print("No loom command detected.")
+        return 1
+    if request.command == "scan":
+        result = scan_topic_from_chat(args.message, args.workspace_root)
+        if result is None:
+            print("No loom scan command detected.")
+            return 1
+        print(f"Detected loom scan chat command for topic: {request.workspace}")
+        print_status_summary(args.workspace_root, request.workspace or "")
+        return 0
+    route_args = argparse.Namespace(
+        workspace=request.workspace,
+        workspace_root=args.workspace_root,
+        server_url=DEFAULT_SERVER_URL,
+        message=None,
+    )
+    handlers = {"status": run_status, "confirm": run_confirm, "push": run_push, "pull": run_pull}
+    return handlers.get(request.command, _no_command)(route_args)
+
+
+def _no_command(_: argparse.Namespace) -> int:
+    print("No loom command detected.")
+    return 1

loom/cli_app/skill.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def install_skill(codex_home: Path, workspace_root: Path) -> Path:
+    skill_dir = codex_home / "skills" / "loom-scan"
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    launcher = workspace_root / "scripts" / "loom.py"
+    (skill_dir / "SKILL.md").write_text(render_skill_markdown(workspace_root, launcher), encoding="utf-8")
+    return skill_dir
+
+
+def render_skill_markdown(workspace_root: Path, launcher: Path) -> str:
+    return f"""# loom-scan
+
+Use this skill when the user types a Loom request in chat, especially commands like `loom scan energy` or `loom confirm energy`.
+
+## Purpose
+
+- Provide a fast path for Loom scan requests without doing broad repo exploration first.
+- Generate dataset summaries under `test-project/loom/loom_explore/<topic>`.
+- Track confirmed loom_explore changes in a dedicated git repository.
+- Route sync commands like `loom push energy` and `loom pull energy` into the local CLI fast path.
+- Prefer reading `loom_explore` outputs after the scan instead of reading raw CSV files directly.
+
+## Fast Path
+
+1. Do not browse unrelated files first.
+2. Do not read anything under `wiki/discard`.
+3. Run `uv run python {launcher} route "loom scan <topic>" --workspace-root {workspace_root}`.
+4. Or run `uv run python {launcher} scan <topic> --workspace-root {workspace_root}`.
+"""

loom/csv_profile.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+from collections import Counter, deque
+import csv
+from dataclasses import dataclass, field
+import math
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class NumericStats:
+    count: int = 0
+    minimum: float | None = None
+    maximum: float | None = None
+    total: float = 0.0
+
+    def update(self, value: float) -> None:
+        self.count += 1
+        self.total += value
+        if self.minimum is None or value < self.minimum:
+            self.minimum = value
+        if self.maximum is None or value > self.maximum:
+            self.maximum = value
+
+    def to_dict(self) -> dict[str, Any]:
+        mean = self.total / self.count if self.count else None
+        return {
+            "count": self.count,
+            "min": self.minimum,
+            "max": self.maximum,
+            "mean": mean,
+        }
+
+
+@dataclass
+class ColumnProfile:
+    name: str
+    non_empty_count: int = 0
+    empty_count: int = 0
+    type_counts: Counter[str] = field(default_factory=Counter)
+    unique_examples: Counter[str] = field(default_factory=Counter)
+    numeric_stats: NumericStats = field(default_factory=NumericStats)
+
+    def update(self, raw_value: str) -> None:
+        value = raw_value.strip()
+        if not value:
+            self.empty_count += 1
+            return
+
+        self.non_empty_count += 1
+        inferred_type, parsed = _infer_value_type(value)
+        self.type_counts[inferred_type] += 1
+
+        if inferred_type == "number" and isinstance(parsed, float):
+            self.numeric_stats.update(parsed)
+        elif len(self.unique_examples) < 20 or value in self.unique_examples:
+            self.unique_examples[value] += 1
+
+    def to_dict(self) -> dict[str, Any]:
+        result: dict[str, Any] = {
+            "name": self.name,
+            "non_empty_count": self.non_empty_count,
+            "empty_count": self.empty_count,
+            "type_counts": dict(self.type_counts),
+        }
+
+        if self.numeric_stats.count:
+            result["numeric_stats"] = self.numeric_stats.to_dict()
+
+        if self.unique_examples:
+            result["top_values"] = [
+                {"value": value, "count": count}
+                for value, count in self.unique_examples.most_common(10)
+            ]
+
+        return result
+
+
+def profile_csv(csv_path: Path, sample_size: int = 10) -> dict[str, Any]:
+    file_size = csv_path.stat().st_size
+    if file_size == 0:
+        return {
+            "file_name": csv_path.name,
+            "file_size_bytes": 0,
+            "dialect": {"delimiter": ","},
+            "columns": [],
+            "row_count": 0,
+            "head": [],
+            "tail": [],
+            "notes": ["File is empty."],
+        }
+
+    with csv_path.open("r", encoding="utf-8-sig", newline="") as handle:
+        sample = handle.read(4096)
+        handle.seek(0)
+        dialect = _sniff_dialect(sample)
+        reader = csv.DictReader(handle, dialect=dialect)
+
+        fieldnames = reader.fieldnames or []
+        columns = [ColumnProfile(name=name) for name in fieldnames]
+        head_rows: list[dict[str, str]] = []
+        tail_rows: deque[dict[str, str]] = deque(maxlen=sample_size)
+        row_count = 0
+
+        for row in reader:
+            normalized_row = {name: row.get(name, "") or "" for name in fieldnames}
+            if len(head_rows) < sample_size:
+                head_rows.append(normalized_row)
+            tail_rows.append(normalized_row)
+            row_count += 1
+
+            for column in columns:
+                column.update(normalized_row.get(column.name, ""))
+
+    notes: list[str] = []
+    if not fieldnames:
+        notes.append("CSV file does not contain a header row.")
+    if row_count == 0:
+        notes.append("CSV file contains a header but no data rows.")
+
+    return {
+        "file_name": csv_path.name,
+        "file_size_bytes": file_size,
+        "dialect": {"delimiter": dialect.delimiter},
+        "columns": [column.to_dict() for column in columns],
+        "row_count": row_count,
+        "head": head_rows,
+        "tail": list(tail_rows),
+        "notes": notes,
+    }
+
+
+def _sniff_dialect(sample: str) -> csv.Dialect:
+    if not sample.strip():
+        return csv.get_dialect("excel")
+
+    try:
+        return csv.Sniffer().sniff(sample, delimiters=",\t;|")
+    except csv.Error:
+        return csv.get_dialect("excel")
+
+
+def _infer_value_type(value: str) -> tuple[str, Any]:
+    lowered = value.lower()
+    if lowered in {"true", "false", "yes", "no"}:
+        return "boolean", lowered in {"true", "yes"}
+
+    try:
+        number = float(value)
+    except ValueError:
+        return "string", value
+
+    if math.isfinite(number):
+        return "number", number
+
+    return "string", value