agent-readable

agent-readable

Stop coding agents from hallucinating Python APIs. agent_help(target) reads the live public API surface from any Python class, module, function, or method and renders compact, agent-oriented Markdown with current signatures and docstring summaries. When a library opts in, it can also return class-level usage rules such as lifecycle order, preconditions, and anti-patterns.

To let your coding agent automatically call agent_help() before using an unfamiliar API, install the companion skill:

npx skills add zydo/skills --skill agent-readable

logging.Logger compared with agent_help() and help()

Quickstart

See Getting started for installation and one-off CLI usage in two parallel series — uv and pip.

from agent_readable import agent_help
import logging

print(agent_help(logging.Logger))

agent_help() works on plain Python objects with no setup required. It returns a curated public API list from runtime introspection, so agents see what exists in the installed version instead of guessing from stale training data.

Library authors can optionally add usage rules next to the code:

class Sensor:
    """Reads a value from a hardware sensor."""

    def read(self) -> float:
        """Read the current sensor value."""

    @classmethod
    def __agent_notes__(cls) -> str:
        return """
## Do

- Call `calibrate()` once during setup, before `read()`.

## Do not

- Do not call `read()` before calibration on first use.
"""

Docs

• Getting started: installation, quickstart, CLI usage, and other language implementations.
• Why it matters: the API hallucination problem, token efficiency, and how this compares to other agent-doc patterns.
• Examples: wrapping existing classes, inherited notes, duck typing, plain classes, modules, functions, and methods.
• Authoring guide: __agent_help__, __agent_notes__, class docstring hints, freshness guidance, and API reference.
• FAQ: common questions about agent skills, docstrings, AGENTS.md, third-party libraries, and constrained decoding.
• Benchmark: methodology and harness measuring whether agent_help() context reduces hallucinated-API failures.

Other Languages

• TypeScript: agent-readable-ts

License

MIT