plexus.documentation.repository module

Frontmatter-aware documentation repository.

The repository exposes the agent-facing documentation tree as an indexed collection of structured entries. Each markdown file in the tree is expected to begin with a YAML frontmatter block; files without frontmatter are surfaced as invalid (they are not silently dropped, so authors notice).

The repository is the single source of truth that the Tactus runtime plexus.docs.list and plexus.docs.get calls delegate to. There is one canonical lookup path: by the id declared in frontmatter.

class plexus.documentation.repository.Document(metadata: dict[str, Any], body: str, path: str)

Bases: object

A single resolved documentation entry.

__init__(metadata: dict[str, Any], body: str, path: str) → None

body: str

property id: str

metadata: dict[str, Any]

path: str

class plexus.documentation.repository.DocumentationRepository(root_dir: str)

Bases: object

Index a documentation tree rooted at root_dir.

The repository is intentionally stateless beyond the root path; each list_docs and get_doc call walks the tree fresh so updates on disk are immediately visible. The tree is small enough that this is fine in practice, and it keeps test isolation simple.

__init__(root_dir: str) → None

get_doc(doc_id: str) → Document

Return the full document for doc_id.

Raises InvalidDocumentationKeyError for unsafe keys or for ids that do not resolve to an indexed file.

list_docs(*, namespace: str | None = None) → ListResult

Return metadata summaries for every indexable doc.

README.md and _index.md files are excluded from the listing. Files without frontmatter are reported under ListResult.invalid instead of raising, so a single bad file does not break the whole index.

property root: str

class plexus.documentation.repository.InvalidDocumentationFile(path: str, reason: str)

Bases: object

A markdown file that could not be indexed.

__init__(path: str, reason: str) → None

path: str

reason: str

exception plexus.documentation.repository.InvalidDocumentationKeyError

Bases: ValueError

Raised when a caller asks for a doc id that is unsafe or unknown.

class plexus.documentation.repository.ListResult(entries: list[dict[str, ~typing.Any]]=<factory>, invalid: list[InvalidDocumentationFile] = <factory>)

Bases: object

Result of a DocumentationRepository.list_docs() call.

__init__(entries: list[dict[str, ~typing.Any]]=<factory>, invalid: list[InvalidDocumentationFile] = <factory>) → None

entries: list[dict[str, Any]]

invalid: list[InvalidDocumentationFile]