Source code for flexcompute.flow_report.guidance

"""Packaged instructions for AI-assisted interactive Report workflows."""

import sys
from importlib.resources import files
from pathlib import Path




def get_agent_guide() -> str:
    """Return the authoritative guide to inject before an AI agent uses this package.

    Agent runners should add the returned Markdown to their system or developer
    instructions before sending the user's task to the model. Calling this function
    is deterministic; installing the wheel alone does not make an agent read its docs.
    """
    packaged_guide = files("flexcompute.flow_report").joinpath("docs").joinpath("agent-guide.md")
    if packaged_guide.is_file():
        return packaged_guide.read_text(encoding="utf-8")

    source_guide = Path(__file__).resolve().parents[3] / "docs" / "agent-guide.md"
    if source_guide.is_file():
        return source_guide.read_text(encoding="utf-8")

    raise FileNotFoundError("Could not locate the packaged or source AI agent guide")



def main() -> None:
    """Print the packaged AI agent guide to standard output."""
    sys.stdout.write(get_agent_guide())


if __name__ == "__main__":
    main()