agent-readable 0.1.0__py3-none-any.whl

agent_readable/__init__.py

@@ -0,0 +1,7 @@
+from importlib.metadata import version
+
+from ._protocol import AgentReadable, AgentReadableMixin, agent_help
+
+__version__ = version("agent-readable")
+
+__all__ = ["AgentReadable", "AgentReadableMixin", "agent_help", "__version__"]

agent_readable/__main__.py

@@ -0,0 +1,55 @@
+"""CLI: ``python -m agent_readable package.module:ClassName``,
+``python -m agent_readable package.module.ClassName``,
+or ``python -m agent_readable package.module``."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+import types
+
+from . import agent_help
+
+
+def _resolve(dotted_path: str) -> type | types.ModuleType:
+    """Import and resolve a target path to a class or module.
+
+    Accepts ``package.module:ClassName``, ``package.module.ClassName``, or
+    ``package.module``.
+    """
+    if ":" in dotted_path:
+        module_path, _, attr = dotted_path.partition(":")
+    elif "." in dotted_path:
+        module_path, _, attr = dotted_path.rpartition(".")
+    else:
+        return importlib.import_module(dotted_path)
+
+    module = importlib.import_module(module_path)
+
+    for part in attr.split(".") if attr else []:
+        module = getattr(module, part)
+
+    if not isinstance(module, type) and not isinstance(module, types.ModuleType):
+        raise TypeError(
+            f"{dotted_path!r} resolved to {type(module).__name__}, "
+            "expected a class or module"
+        )
+
+    return module
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print(
+            "Usage: python -m agent_readable "
+            "(package.module:ClassName | package.module.ClassName | package.module)",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    target = _resolve(sys.argv[1])
+    print(agent_help(target))
+
+
+if __name__ == "__main__":
+    main()

agent_readable/_protocol.py

@@ -0,0 +1,363 @@
+from __future__ import annotations
+
+import inspect
+import types
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class AgentReadable(Protocol):
+    """Protocol for classes that expose agent-oriented documentation.
+
+    Implementing ``__agent_help__()`` opts the class into **full replacement**:
+    the returned string IS what ``agent_help(cls)`` returns, verbatim. Notes from
+    ``__agent_notes__()`` are NOT auto-appended — implementers control the entire
+    output. To get auto-doc + appended notes instead, use ``AgentReadableMixin``
+    (or just define ``__agent_notes__()`` and let the auto-doc path run).
+    """
+
+    @classmethod
+    def __agent_help__(cls) -> str:
+        """Return agent-oriented help for this class (full output, verbatim)."""
+        ...
+
+
+class AgentReadableMixin:
+    """
+    Optional mixin for classes that want agent-readable documentation.
+
+    Deriving from this mixin gives your class a default ``__agent_help__()`` that
+    auto-generates structured docs from introspection.
+
+    Optionally, to append more help instructions to coding agents, override
+    ``__agent_notes__()`` to add usage examples, do/don't rules, and anti-patterns, etc.
+    """
+
+    @classmethod
+    def __agent_help__(cls) -> str:
+        """Return agent-oriented help for this class.
+
+        Do NOT override this method directly. To add custom notes, override
+        ``__agent_notes__()`` instead.
+
+        Coding agents:
+            Call ``agent_help(TheClass)`` to learn how to use the class before
+            generating code that uses it. Treat the output as the canonical usage guide.
+        """
+        return _base_agent_doc(cls)
+
+    @classmethod
+    def __agent_notes__(cls) -> str:
+        """
+        Additive custom guidance, collected from every class in the MRO.
+
+        Unlike ``__agent_help__`` (which replaces the entire output),
+        ``__agent_notes__`` is **appended** to the auto-generated docs and
+        **accumulates across the MRO** — every class that defines its own
+        ``__agent_notes__`` contributes a section. The leaf class is tagged as
+        taking precedence over inherited notes when they conflict.
+
+        Do not prepend ``super().__agent_notes__()`` — collection is automatic.
+        Defining this method on any class is enough; the ``AgentReadableMixin``
+        is not required.
+        """
+        return ""
+
+
+def agent_help(obj: Any) -> str:
+    """
+    Return agent-oriented help for a class, instance, or module.
+
+    Dispatch for classes/instances:
+
+    1. **``__agent_help__()`` is defined** — call it and return its result
+       verbatim. The ``AgentReadableMixin`` default returns
+       ``_base_agent_doc(cls)`` (auto-doc with ``__agent_notes__`` appended);
+       duck-typed implementations return whatever the user formatted, so notes
+       are NOT auto-included on that path — the implementer owns the full
+       output.
+    2. **``__agent_help__`` is missing** — fall through to
+       ``_base_agent_doc(cls)``, which appends ``__agent_notes__()`` from every
+       class in the MRO automatically.
+    3. **``__agent_help__()`` raises** — same fallback as path 2 (auto-doc with
+       notes).
+
+    Notes accumulation lives in ``_base_agent_doc()``, which is why duck-typed
+    ``__agent_help__()`` skips it: that path never reaches ``_base_agent_doc``.
+
+    For modules: if the module defines a ``__agent_help__`` attribute (callable
+    or string), it is used directly. Otherwise auto-generated docs are produced
+    via ``_module_doc()``. Module ``__agent_notes__`` is not part of the
+    protocol — modules don't have an MRO to accumulate over.
+    """
+    if inspect.ismodule(obj):
+        fn = getattr(obj, "__agent_help__", None)
+        if callable(fn):
+            try:
+                result = fn()
+                if isinstance(result, str):
+                    return result
+                return str(result)
+            except Exception:
+                pass
+        if isinstance(fn, str):
+            return fn
+        return _module_doc(obj)
+
+    target = obj if inspect.isclass(obj) else obj.__class__
+
+    fn = getattr(target, "__agent_help__", None)
+    if callable(fn):
+        try:
+            result = fn()
+            if isinstance(result, str):
+                return result
+            return str(result)
+        except Exception:
+            pass
+
+    return _base_agent_doc(target)
+
+
+def _module_doc(module: types.ModuleType) -> str:
+    """Generate compact Markdown documentation for a module."""
+    parts: list[str] = []
+
+    parts.append(f"# {module.__name__}")
+    parts.append("")
+
+    doc = inspect.getdoc(module)
+    if doc:
+        parts.append("## Purpose")
+        parts.append("")
+        parts.append(doc)
+        parts.append("")
+
+    public_api = _collect_module_api(module)
+    if public_api:
+        parts.append("## Public API")
+        parts.append("")
+        parts.extend(public_api)
+        parts.append("")
+
+    parts.append("## Agent usage rules")
+    parts.append("")
+    parts.append("- Prefer the public API listed above.")
+    parts.append("- Do not use private names starting with `_`.")
+    parts.append("- Do not invent unsupported behavior.")
+    parts.append(
+        "- If usage is ambiguous, prefer the simplest documented usage pattern."
+    )
+
+    return "\n".join(parts)
+
+
+def _collect_module_api(module: types.ModuleType) -> list[str]:
+    lines: list[str] = []
+    mod_name = module.__name__
+    for name, obj in inspect.getmembers(module):
+        if name.startswith("_"):
+            continue
+        obj_module = getattr(obj, "__module__", None)
+        if (
+            obj_module is not None
+            and obj_module != mod_name
+            and not obj_module.startswith(mod_name + ".")
+        ):
+            continue
+        if inspect.isclass(obj):
+            summary = _first_doc_line(obj)
+            line = f"- `{name}` class"
+            if summary:
+                line += f": {summary}"
+            lines.append(line)
+        elif inspect.isfunction(obj):
+            sig = _safe_signature(obj)
+            summary = _first_doc_line(obj)
+            line = f"- `{name}{sig}` function"
+            if summary:
+                line += f": {summary}"
+            lines.append(line)
+        elif isinstance(obj, types.ModuleType):
+            continue
+    return lines
+
+
+def _base_agent_doc(cls: type) -> str:
+    """
+    Generate compact Markdown documentation for AI coding agents.
+
+    Appends ``__agent_notes__()`` from every class in ``cls.__mro__``,
+    whether or not the class uses ``AgentReadableMixin``.
+    """
+    parts: list[str] = []
+
+    parts.append(f"# {cls.__name__}")
+    parts.append("")
+
+    constructor = _format_constructor(cls)
+    if constructor:
+        parts.append("## Constructor")
+        parts.append("")
+        parts.append("```python")
+        parts.append(constructor)
+        parts.append("```")
+        parts.append("")
+
+    doc = inspect.getdoc(cls)
+    if doc:
+        parts.append("## Purpose")
+        parts.append("")
+        parts.append(doc)
+        parts.append("")
+
+    public_api = _collect_public_api(cls)
+    if public_api:
+        parts.append("## Public API")
+        parts.append("")
+        parts.extend(public_api)
+        parts.append("")
+
+    parts.append("## Agent usage rules")
+    parts.append("")
+    parts.append("- Prefer the public API listed above.")
+    parts.append("- Do not use private methods or attributes starting with `_`.")
+    parts.append("- Do not invent unsupported behavior.")
+    parts.append(
+        "- If usage is ambiguous, prefer the simplest documented usage pattern."
+    )
+
+    base = "\n".join(parts)
+    notes = _collect_agent_notes(cls)
+    if notes:
+        return base + "\n\n" + "\n\n".join(notes)
+    return base
+
+
+def _collect_agent_notes(cls: type) -> list[str]:
+    """Collect ``__agent_notes__()`` sections from every class in ``cls.__mro__``.
+
+    Each class that defines its own ``__agent_notes__`` becomes a Markdown section.
+    The leaf class's notes are tagged as taking precedence over inherited ones when
+    conflicts arise.
+    """
+    notes: list[str] = []
+    parent_names: list[str] = []
+    for klass in reversed(cls.__mro__):
+        raw = klass.__dict__.get("__agent_notes__")
+        if raw is None:
+            continue
+        fn = raw.__func__ if isinstance(raw, classmethod) else raw
+        result = fn(cls)
+        if result:
+            header = f"## Notes from class {klass.__name__}"
+            if klass is cls and parent_names:
+                header += (
+                    f" (inherits {', '.join(parent_names)}; "
+                    "if notes conflict, these take precedence)"
+                )
+            notes.append(header + "\n\n" + result.strip())
+            if klass is not cls:
+                parent_names.append(klass.__name__)
+    return notes
+
+
+def _format_constructor(cls: type) -> str | None:
+    try:
+        signature = inspect.signature(cls)
+    except (TypeError, ValueError):
+        return None
+
+    return f"{cls.__name__}{signature}"
+
+
+def _collect_public_api(cls: type) -> list[str]:
+    lines: list[str] = []
+
+    for name, _ in inspect.getmembers(cls):
+        if name.startswith("_"):
+            continue
+
+        try:
+            raw = inspect.getattr_static(cls, name)
+        except AttributeError:
+            continue
+
+        if isinstance(raw, property):
+            summary = _first_doc_line(raw)
+            line = f"- `{name}` property"
+            if summary:
+                line += f": {summary}"
+            lines.append(line)
+            continue
+
+        if isinstance(raw, staticmethod):
+            fn = raw.__func__
+            kind = "staticmethod"
+        elif isinstance(raw, classmethod):
+            fn = raw.__func__
+            kind = "classmethod"
+        elif inspect.isfunction(raw) or (callable(raw) and not isinstance(raw, type)):
+            fn = raw
+            kind = "method"
+        else:
+            continue
+
+        sig = _safe_signature(fn)
+        if (kind == "method" or kind == "classmethod") and sig != "(...)":
+            sig = _strip_first_param(sig)
+        summary = _first_doc_line(fn)
+
+        line = f"- `{name}{sig}` {kind}"
+        if summary:
+            line += f": {summary}"
+
+        lines.append(line)
+
+    return lines
+
+
+def _safe_signature(obj: Any) -> str:
+    try:
+        return str(inspect.signature(obj))
+    except (TypeError, ValueError):
+        return "(...)"
+
+
+def _strip_first_param(sig: str) -> str:
+    """Strip the first parameter (``self`` / ``cls``) from a signature string.
+
+    Input is always produced by ``inspect.signature(...)`` and therefore starts
+    with ``(`` and contains a balanced closing ``)``.
+    """
+    rest = sig[1:]  # drop leading "("
+    depth = 0
+    for i, ch in enumerate(rest):
+        if ch in "([":
+            depth += 1
+        elif ch in ")]":
+            if depth > 0:
+                depth -= 1
+            else:
+                return "()" + rest[i + 1 :]
+        elif ch == "," and depth == 0:
+            return "(" + rest[i + 1 :].lstrip()
+    return (
+        "()"  # pragma: no cover -- unreachable: inspect.signature always closes parens
+    )
+
+
+def _first_doc_line(obj: Any) -> str:
+    doc = inspect.getdoc(obj)
+    if not doc:
+        return ""
+
+    paragraph: list[str] = []
+    for line in doc.splitlines():
+        stripped = line.strip()
+        if stripped:
+            paragraph.append(stripped)
+        elif paragraph:
+            break
+
+    return " ".join(paragraph)

agent_readable-0.1.0.dist-info/METADATA

@@ -0,0 +1,622 @@
+Metadata-Version: 2.4
+Name: agent-readable
+Version: 0.1.0
+Summary: A lightweight protocol for exposing agent-oriented documentation from Python classes and modules
+Project-URL: Repository, https://github.com/zydo/agent-readable
+Author: zydo and agent-readable contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,agent-help,ai,ai-agent,coding-agent,context-engineering,docstring,documentation,llm,mixin,prompt-engineering,protocol,vibe-coding
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# agent-readable
+
+A lightweight Python protocol for exposing agent-oriented documentation from classes and modules.
+
+## Problem
+
+AI coding agents recognize established libraries from their training data, but they hallucinate when APIs change, when libraries are new, or when correct usage depends on rules that aren't visible from the API surface — pre-conditions, lifecycle order, anti-patterns, *"use `call()` for non-streaming, `stream()` for streaming."*
+
+Today there's nowhere to put those rules where an agent will reliably find them. Docstrings document the API surface, not behavioral rules. `AGENTS.md` and `llms.txt` work at project granularity, drift fast, and don't travel with refactors. `help()` is verbose and only describes interfaces.
+
+`agent-readable` adds two dunders — `__agent_help__` (full custom output) and `__agent_notes__` (additive guidance that accumulates across inheritance) — that live next to the code. Library authors annotate once; any agent that calls `agent_help(cls)` gets the rules.
+
+```text
+help(logging.Logger)        217 lines — every inherited method, dunder, and MRO detail.
+agent_help(logging.Logger)   56 lines — structured sections + any author notes.
+```
+
+The compactness is a side effect; the structure is the point.
+
+## Installation
+
+```bash
+pip install agent-readable
+```
+
+Requires Python 3.10+. No runtime dependencies.
+
+## Quickstart
+
+```python
+from agent_readable import AgentReadableMixin, agent_help
+
+
+class Sensor(AgentReadableMixin):
+    """Reads a value from a hardware sensor."""
+
+    def __init__(self, pin: int, *, unit: str = "C"): ...
+
+    def read(self) -> float:
+        """Read the current sensor value."""
+
+    def calibrate(self, offset: float):
+        """Apply a calibration offset."""
+
+    @classmethod
+    def __agent_notes__(cls) -> str:
+        return """
+## Do
+
+- Call `calibrate()` once during setup, before `read()`.
+
+## Do not
+
+- Do not call `read()` before `calibrate()` on first use.
+"""
+
+
+print(agent_help(Sensor))
+```
+
+Output:
+
+````
+# Sensor
+
+## Constructor
+
+```python
+Sensor(pin: int, *, unit: str = 'C')
+```
+
+## Purpose
+
+Reads a value from a hardware sensor.
+
+## Public API
+
+- `calibrate(offset: float)` method: Apply a calibration offset.
+- `read() -> float` method: Read the current sensor value.
+
+## Agent usage rules
+
+- Prefer the public API listed above.
+- Do not use private methods or attributes starting with `_`.
+- Do not invent unsupported behavior.
+- If usage is ambiguous, prefer the simplest documented usage pattern.
+
+## Notes from class Sensor
+
+## Do
+
+- Call `calibrate()` once during setup, before `read()`.
+
+## Do not
+
+- Do not call `read()` before `calibrate()` on first use.
+````
+
+## Why it matters
+
+`help()` documents the **API surface** — what each method does. But agents fail less often on *what methods exist* than on *how to use them*: lifecycle order, pre-conditions, anti-patterns, "this method is for X, that one for Y." Those rules don't fit in docstrings (which describe single methods) and don't belong in a project-level `AGENTS.md` (which describes whole repos). They're class-level, and they need to travel with refactors.
+
+`agent_help()` gives them a home next to the code:
+
+```
+# help(sqlite3.Connection) — 200+ lines of terminal output:
+Help on class Connection in module sqlite3:
+
+class Connection(builtins.object)
+ |  SQLite database connection object.
+ |
+ |  Methods defined here:
+ |
+ |  __call__(self, /, *args, **kwargs)
+ |  __del__(self, /, *args, **kwargs)
+ |  __enter__(self, /, *args, **kwargs)
+ |  ...
+ |  backup(self, target, /, *, pages=-1, progress=None, ...)
+ |  blobopen(self, table, column, rowid, /, *, readonly=False, ...)
+ |  ... (continues for 200+ more lines)
+```
+
+`agent_help(sqlite3.Connection)` produces a scannable summary instead — see Example 1 below. Notes from `__agent_notes__()` accumulate across inheritance. Class docs travel with the code in commits, reviews, and refactors. Drift gets caught in code review, not weeks later in a sidecar file.
+
+The examples below demonstrate four ways to use `agent_help()`.
+
+## Example 1: Wrapping an existing class
+
+Add agent-readable docs to any class, including ones you don't own. Full example: [`examples/sqlite_connection.py`](examples/sqlite_connection.py).
+
+```python
+import sqlite3
+from agent_readable import AgentReadableMixin, agent_help
+
+
+class Connection(sqlite3.Connection, AgentReadableMixin):
+    """An agent-friendly wrapper around sqlite3.Connection."""
+
+    @classmethod
+    def __agent_notes__(cls) -> str:
+        return (
+            "Additional notes about using Connection here. "
+            "For example, common pitfalls, best practices, etc."
+        )
+```
+
+Override `__agent_notes__()` to add extra guidance, or leave it out for auto-generated docs only.
+
+`agent_help(Connection)` output:
+
+```
+# Connection
+
+## Purpose
+
+An agent-friendly wrapper around sqlite3.Connection.
+
+## Public API
+
+- `backup(/, target, *, pages=-1, progress=None, name='main', sleep=0.25)` method: Makes a backup of the database.
+- ...
+- `close(/)` method: Close the database connection.
+- `commit(/)` method: Commit any pending transaction to the database.
+- ...
+- `execute(...)` method: Executes an SQL statement.
+- ...
+- `rollback(/)` method: Roll back to the start of any pending transaction.
+- ...
+
+## Agent usage rules
+
+- Prefer the public API listed above.
+- Do not use private methods or attributes starting with `_`.
+- Do not invent unsupported behavior.
+- If usage is ambiguous, prefer the simplest documented usage pattern.
+
+## Notes from class Connection
+
+Additional notes about using Connection here. For example, common pitfalls, best practices, etc.
+```
+
+## Example 2: Inheritance with accumulated notes
+
+Override `__agent_notes__()` to add usage guidance. Notes accumulate through inheritance automatically. Full example: [`examples/temperature.py`](examples/temperature.py).
+
+```python
+from agent_readable import AgentReadableMixin, agent_help
+
+
+class Sensor(AgentReadableMixin):
+    """Reads a value from a hardware sensor."""
+
+    def __init__(self, pin: int, *, unit: str = "C"): ...
+
+    def read(self) -> float:
+        """Read the current sensor value."""
+
+    def calibrate(self, offset: float):
+        """Apply a calibration offset."""
+
+    @classmethod
+    def __agent_notes__(cls) -> str:
+        return """
+## Do
+
+- Call `calibrate()` once during setup, before `read()`.
+- Handle negative values — sensors may report below zero.
+
+## Do not
+
+- Do not call `read()` before `calibrate()` on first use.
+"""
+
+
+class CalibratedSensor(Sensor):
+    """A sensor with factory calibration applied."""
+
+    def reset(self):
+        """Reset to factory calibration."""
+
+    @classmethod
+    def __agent_notes__(cls) -> str:
+        return """
+## Do
+
+- Call `reset()` if readings drift unexpectedly.
+
+## Do not
+
+- Do not call `calibrate()` — use `reset()` instead. Factory calibration
+  is pre-applied and `calibrate()` would double-adjust.
+"""
+```
+
+`agent_help(CalibratedSensor)` output — includes inherited notes with conflict resolution:
+
+````
+# CalibratedSensor
+
+## Constructor
+
+```python
+CalibratedSensor(pin: int, *, unit: str = 'C')
+```
+
+## Purpose
+
+A sensor with factory calibration applied.
+
+## Public API
+
+- `calibrate(offset: float)` method: Apply a calibration offset.
+- `read() -> float` method: Read the current sensor value.
+- `reset()` method: Reset to factory calibration.
+
+## Agent usage rules
+
+- Prefer the public API listed above.
+- Do not use private methods or attributes starting with `_`.
+- Do not invent unsupported behavior.
+- If usage is ambiguous, prefer the simplest documented usage pattern.
+
+## Notes from class Sensor
+
+## Do
+
+- Call `calibrate()` once during setup, before `read()`.
+- Handle negative values — sensors may report below zero.
+
+## Do not
+
+- Do not call `read()` before `calibrate()` on first use.
+
+## Notes from class CalibratedSensor (inherits Sensor; if notes conflict, these take precedence)
+
+## Do
+
+- Call `reset()` if readings drift unexpectedly.
+
+## Do not
+
+- Do not call `calibrate()` — use `reset()` instead. Factory calibration
+  is pre-applied and `calibrate()` would double-adjust.
+````
+
+The child class's notes explicitly state they take precedence over the parent's — so the agent knows `reset()` replaces `calibrate()` for `CalibratedSensor`.
+
+## Example 3: Duck-typed (no mixin needed)
+
+Any class that defines a `__agent_help__()` classmethod works — no inheritance required. Full example: [`examples/duck_type.py`](examples/duck_type.py).
+
+```python
+from agent_readable import agent_help
+
+
+class RateLimiter:
+    """Token bucket rate limiter."""
+
+    def __init__(self, max_tokens: int, refill_rate: float): ...
+
+    def acquire(self, tokens: int = 1) -> bool:
+        """Try to acquire tokens. Returns False if rate-limited."""
+
+    def wait(self, tokens: int = 1) -> None:
+        """Block until tokens are available."""
+
+    @classmethod
+    def __agent_help__(cls) -> str:
+        return (
+            "# RateLimiter\n"
+            "\n"
+            "## Constructor\n"
+            "\n"
+            "```python\n"
+            "RateLimiter(max_tokens: int, refill_rate: float)\n"
+            "```\n"
+            "\n"
+            "## Do\n"
+            "\n"
+            "- Use `acquire()` for non-blocking checks.\n"
+            "- Use `wait()` when you must proceed regardless of rate.\n"
+            "- Set `refill_rate` to tokens/second.\n"
+            "\n"
+            "## Do not\n"
+            "\n"
+            "- Do not call `acquire()` in a tight loop without sleeping.\n"
+            "- Do not assume `acquire()` always returns True.\n"
+        )
+
+
+print(agent_help(RateLimiter))
+```
+
+## Example 4: Any class — no setup required
+
+Even without the mixin or duck-typing, `agent_help()` still generates compact, structured Markdown from introspection. If the class (or any class in its MRO) defines `__agent_notes__()`, those notes are auto-appended too — no mixin required. The output is still more agent-friendly than `help()`.
+Full example: [`examples/any_class.py`](examples/any_class.py).
+
+```python
+import logging
+from agent_readable import agent_help
+
+print(agent_help(logging.Logger))
+```
+
+`help(logging.Logger)` produces **217 lines** of output. `agent_help(logging.Logger)` produces a compact, scannable summary:
+
+````
+# Logger
+
+## Constructor
+
+```python
+Logger(name, level=0)
+```
+
+## Purpose
+
+Instances of the Logger class represent a single logging channel. A
+"logging channel" indicates an area of an application.
+
+...
+
+## Public API
+
+- `addFilter(filter)` method: Add the specified filter to this handler.
+- `addHandler(hdlr)` method: Add the specified handler to this logger.
+- ...
+- `debug(msg, *args, **kwargs)` method: Log 'msg % args' with severity 'DEBUG'.
+- `error(msg, *args, **kwargs)` method: Log 'msg % args' with severity 'ERROR'.
+- ...
+- `info(msg, *args, **kwargs)` method: Log 'msg % args' with severity 'INFO'.
+- ...
+- `setLevel(level)` method: Set the logging level of this logger.  level must be an int or a str.
+- ...
+- `warning(msg, *args, **kwargs)` method: Log 'msg % args' with severity 'WARNING'.
+````
+
+No mixin, no duck-typing — just pass any class to `agent_help()`.
+
+## Example 5: Modules
+
+`agent_help()` also works on modules — it generates a summary with the module docstring, public functions, and classes. Full example: [`examples/module_support.py`](examples/module_support.py).
+
+```python
+import sys
+from agent_readable import agent_help
+
+print(agent_help(sys.modules[__name__]))
+```
+
+Output:
+
+````python
+# __main__
+
+## Purpose
+
+Example: Using agent_help() on modules.
+
+Demonstrates both shapes of module support:
+  1. A custom module (this file itself).
+  2. A stdlib module (pathlib).
+
+Run this file to see both outputs:
+    python examples/module_support.py
+
+## Public API
+
+- `Query` class: Build and execute a query.
+- `connect(host: str, port: int = 5432) -> str` function: Connect to a database server.
+- `disconnect()` function: Close the connection.
+
+## Agent usage rules
+
+- Prefer the public API listed above.
+- Do not use private names starting with `_`.
+- Do not invent unsupported behavior.
+- If usage is ambiguous, prefer the simplest documented usage pattern.
+````
+
+You can also pass any stdlib or third-party module — same `module_support.py` shows it.
+
+```python
+import pathlib
+from agent_readable import agent_help
+
+print(agent_help(pathlib))
+```
+
+Output:
+
+````python
+# pathlib
+
+## Purpose
+
+Object-oriented filesystem paths.
+
+This module provides classes to represent abstract paths and concrete
+paths with operations that have semantics appropriate for different
+operating systems.
+
+## Public API
+
+- `DirEntryInfo` class: Implementation of pathlib.types.PathInfo that provides status
+- `Path` class: PurePath subclass that can make system calls.
+- `PathInfo` class: Implementation of pathlib.types.PathInfo that provides status
+- `PosixPath` class: Path subclass for non-Windows systems.
+- `PurePath` class: Base class for manipulating paths without I/O.
+- `PurePosixPath` class: PurePath subclass for non-Windows systems.
+- `PureWindowsPath` class: PurePath subclass for Windows systems.
+- `UnsupportedOperation` class: An exception that is raised when an unsupported operation is attempted.
+- `WindowsPath` class: Path subclass for Windows systems.
+- `copy_info(info, target, follow_symlinks=True)` function: Copy metadata from the given PathInfo to the given local path.
+- `copyfileobj(source_f, target_f)` function: Copy data from file-like object source_f to file-like object target_f.
+- `ensure_different_files(source, target)` function: Raise OSError(EINVAL) if both paths refer to the same file.
+- `ensure_distinct_paths(source, target)` function: Raise OSError(EINVAL) if the other path is within this path.
+- `magic_open(path, mode='r', buffering=-1, encoding=None, errors=None, newline=None)` function: Open the file pointed to by this path and return a file object, as
+
+## Agent usage rules
+
+- Prefer the public API listed above.
+- Do not use private names starting with `_`.
+- Do not invent unsupported behavior.
+- If usage is ambiguous, prefer the simplest documented usage pattern.
+````
+
+Modules support less customization than classes — there is no mixin inheritance or `__agent_notes__()`. You can override the auto-generated output entirely by setting a module-level `__agent_help__` attribute (callable or string), but this is discouraged since it replaces the auto-generated summary — signatures, purpose, and public API listing are all lost. Prefer clear docstrings on the module and its functions/classes instead.
+
+```python
+import sys
+
+# Discouraged — replaces everything, including auto-generated docs.
+sys.modules[__name__].__agent_help__ = "Custom module help."
+```
+
+## CLI
+
+```bash
+# Any stdlib class
+python -m agent_readable sqlite3:Connection
+
+# A class in your own package
+python -m agent_readable my_package.temperature:CalibratedSensor
+
+# The library itself — self-documenting
+python -m agent_readable agent_readable:AgentReadableMixin
+
+# Any module
+python -m agent_readable pathlib
+```
+
+Outputs agent-oriented documentation for the given class or module to stdout.
+
+## FAQ
+
+### How does my agent know to call `agent_help()` instead of `help()`?
+
+Today, you tell it. Either:
+
+- Paste [`AGENT-PROMPT.md`](AGENT-PROMPT.md) into your conversation, or
+- Add it permanently to your repo's `AGENTS.md` / `CLAUDE.md` / `.cursor/rules` / equivalent instruction file.
+
+"You tell it" is the hard part of any new agent protocol. An MCP server (so MCP-aware clients auto-discover the tool) is on the roadmap.
+
+### How is this different from `AGENTS.md` / `llms.txt` / Cursor rules?
+
+Different granularity, different drift profile.
+
+- `AGENTS.md` / `llms.txt` / `.cursor/rules` are **project-level**: one file per repo. Good for *"use pnpm,"* *"run lint before commit,"* *"this codebase prefers functional style."*
+- `agent-readable` is **class- or module-level**: rules live next to the API they describe. Good for *"`ResourcePool.call()` is for non-streaming requests; for streaming, use `stream()` instead."*
+
+Use both — they don't compete. The advantage of class-level: docs travel with the code. When someone refactors `ResourcePool` into two classes, the rules move with them in the same PR; they don't sit stale in a sidecar file.
+
+### Why not just write better docstrings?
+
+Docstrings answer *what does this do?* They aren't designed for *when may I call this?* or *what's the wrong way to use this?* Mixing both into the docstring makes the API summary noisier without helping agents find the rules. `__agent_notes__()` is for the second category, and it accumulates across the MRO automatically — class docstrings don't compose like that.
+
+### Does this work for libraries I don't own?
+
+Yes. Two ways:
+
+- Subclass + `AgentReadableMixin` (Example 1).
+- Monkey-patch: `ThirdPartyClass.__agent_notes__ = classmethod(lambda cls: "...")`. `agent_help()` collects notes from the entire MRO; the mixin is not required.
+
+### Does it work without my class doing anything?
+
+Yes — `agent_help()` falls back to introspection (Example 4). You get a structured summary of every plain class, mixin or not. Notes are added on top *if* the class defines them; otherwise the auto-doc is what you see.
+
+## Keeping agent docs up to date
+
+Agent docs can go stale when classes change — new methods, changed behavior, removed APIs. Copy [`AGENT-PROMPT.md`](AGENT-PROMPT.md) into your coding agent's conversation, or permanently add it to your repo's `AGENTS.md`, `CLAUDE.md`, `.cursor/rules`, `.trae/rules`, `.github/copilot-instructions.md`, or equivalent instruction file. It tells your coding agent to run `agent_help()` before modifying a class, prefer docstrings over `__agent_notes__()`, and verify that docs stay accurate after changes.
+
+## The `__agent_help__` protocol
+
+`__agent_help__()` is a dunder protocol, similar in spirit to ecosystem protocols such as:
+
+- `__str__` (str) — string representation
+- `__rich_repr__` (Rich) — custom console representation
+- `__html__` (Django, Jinja2) — HTML rendering
+- `__array__` (NumPy) — array conversion
+- `__fspath__` (os.fspath) — filesystem path conversion
+
+Classes that define a `@classmethod` named `__agent_help__` returning a `str` are considered agent-readable. Modules can define a top-level `__agent_help__` attribute (callable or string). Call the top-level `agent_help(obj)` function to get the docs — just like `str()` calls `__str__()`. The `AgentReadable` `typing.Protocol` and `AgentReadableMixin` are provided for convenience and type-checking, but neither is required.
+
+### `__agent_help__` vs `__agent_notes__`
+
+The two dunders intentionally encode different composition rules:
+
+| Aspect          | `__agent_help__()`                              | `__agent_notes__()`                                                         |
+|-----------------|-------------------------------------------------|-----------------------------------------------------------------------------|
+| Semantics       | **Replacement** — returned string IS the output | **Additive** — appended to auto-generated docs                              |
+| Composition     | Single class wins (the one closest in MRO)      | Accumulated across the MRO; leaf class wins on conflict (header marks this) |
+| When to use     | Total control over the rendered text            | "Auto-doc + my extra do/don't rules"                                        |
+| Skipped when    | (always called if defined)                      | Skipped when a duck-typed `__agent_help__` is present (it owns the output)  |
+| Mixin required? | No — duck-typed classmethod is enough           | No — defining `__agent_notes__` on any class is enough                      |
+
+## Class docstring hints
+
+For classes that inherit `AgentReadableMixin`, add a short hint in the class docstring:
+
+```python
+class ResourcePool(AgentReadableMixin):
+    """
+    Rotates interchangeable resources such as API keys.
+
+    Agent usage:
+        Run ``agent_help(ResourcePool)`` before using this class in generated code.
+    """
+```
+
+This way, even agents that only see the source or call `help()` are reminded to check `agent_help()`.
+
+## API reference
+
+### `AgentReadable`
+
+A `typing.Protocol` (runtime-checkable) that requires `__agent_help__() -> str`.
+
+### `AgentReadableMixin`
+
+A mixin class for *classes* providing a default `__agent_help__()` implementation that generates structured Markdown from introspection. The mixin is convenience — defining `__agent_notes__()` directly on any class (no inheritance) also works; notes are collected automatically regardless. The mixin does not apply to modules; modules are supported directly by `agent_help()`.
+
+If a class inherits from `AgentReadableMixin`, coding agents should call `agent_help(TheClass)` before generating code that uses it.
+
+### `agent_help(obj)`
+
+Returns a string of agent-oriented documentation for a class, instance, or module.
+
+- For classes and instances: if `__agent_help__()` is defined (via mixin or duck-typing), it is called and its return value is used verbatim — duck-typed implementations are responsible for their own formatting and notes are NOT auto-appended. Otherwise, auto-generated docs are produced from introspection, with `__agent_notes__()` from every class in the MRO appended automatically. If `__agent_help__()` raises, falls back to the auto-generated path (which does include notes).
+- For modules: if the module defines a `__agent_help__` attribute (callable or string), it is used. Otherwise, auto-generated docs are produced from the module docstring and its public functions and classes.
+
+## License
+
+MIT

agent_readable-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+agent_readable/__init__.py,sha256=257u1njad3rF_T8sQ3jlzf7RCStS34koSH-3ChdnygY,230
+agent_readable/__main__.py,sha256=8mf7bomOzOl7RgWcoFe2oESTbKa2OTBW8lc21NCBW3M,1487
+agent_readable/_protocol.py,sha256=Em1YNBfKnNJI3xmhEbxO1BnxLA2i8J8gUnv9qJ4qXBI,11557
+agent_readable-0.1.0.dist-info/METADATA,sha256=2lqK-OPe8KwnNrFiPPZCEgDr_e0aOVg4pKwmWOv-088,22995
+agent_readable-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+agent_readable-0.1.0.dist-info/licenses/LICENSE,sha256=e9e5wQN-xeo0CxeZJIlbXjA7pF7vpCSa6hWYYQVUVN0,1093
+agent_readable-0.1.0.dist-info/RECORD,,

agent_readable-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_readable-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zydo and agent-readable contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.