unity_agent/knowledge/__init__.py

"""Knowledge base loader.

Provides a simple API for loading the markdown knowledge entries that ship
with the package. Entries are stored as ``.md`` files in
``unity_agent/knowledge/entries/``.
"""

from __future__ import annotations

from importlib import resources
from pathlib import Path
from typing import Dict, List, Optional


def entries_dir() -> Path:
    """Return the absolute path to the knowledge entries directory."""
    return Path(__file__).resolve().parent / "entries"


def list_entries() -> List[str]:
    """Return a list of knowledge entry slugs (file names without .md)."""
    d = entries_dir()
    if not d.exists():
        return []
    return sorted(p.stem for p in d.glob("*.md"))


def load_entry(slug: str) -> Optional[str]:
    """Return the markdown body of a knowledge entry, or None if missing."""
    p = entries_dir() / f"{slug}.md"
    if not p.exists():
        return None
    return p.read_text(encoding="utf-8")


def load_all() -> Dict[str, str]:
    """Return a dict mapping slug -> markdown body for every entry."""
    return {slug: load_entry(slug) for slug in list_entries()}


__all__ = ["entries_dir", "list_entries", "load_entry", "load_all"]