agent-readable 0.1.0__tar.gz → 0.1.1__tar.gz

{agent_readable-0.1.0 → agent_readable-0.1.1}/AGENT-PROMPT.md

@@ -15,6 +15,12 @@ print(agent_help(ClassName))
 # or
 print(agent_help(package.module))
 # or: python -m agent_readable package.module
+
+# functions and methods also work
+print(agent_help(package.module.func))
+print(agent_help(ClassName.method))
+# or: python -m agent_readable package.module:func
+# or: python -m agent_readable package.module:ClassName.method
 ```
 
 Treat the output as the canonical usage guide. Follow do/don't rules, anti-patterns, and lifecycle constraints exactly. Do not invent behavior that contradicts it.

{agent_readable-0.1.0 → agent_readable-0.1.1}/PKG-INFO

@@ -1,7 +1,7 @@
 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
+Version: 0.1.1
+Summary: A lightweight Python protocol for agent-oriented documentation
 Project-URL: Repository, https://github.com/zydo/agent-readable
 Author: zydo and agent-readable contributors
 License-Expression: MIT
@@ -28,6 +28,13 @@ Description-Content-Type: text/markdown
 
 A lightweight Python protocol for exposing agent-oriented documentation from classes and modules.
 
+<!-- markdownlint-disable MD033 -->
+<p align="center">
+  <strong><code>logging.Logger</code> compared with <code>agent_help()</code> and <code>help()</code></strong><br>
+  <img src="docs/agent_help_vs_help.gif" alt="agent_help vs help">
+</p>
+<!-- markdownlint-enable MD033 -->
+
 ## 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."*
@@ -404,9 +411,9 @@ Instances of the Logger class represent a single logging channel. A
 
 No mixin, no duck-typing — just pass any class to `agent_help()`.
 
-## Example 5: Modules
+## Example 5: Modules, functions, and methods
 
-`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).
+`agent_help()` also works on modules — it generates a summary with the module docstring, public functions, and classes. Full example: [`examples/modules_and_functions.py`](examples/modules_and_functions.py).
 
 ```python
 import sys
@@ -429,7 +436,7 @@ Demonstrates both shapes of module support:
   2. A stdlib module (pathlib).
 
 Run this file to see both outputs:
-    python examples/module_support.py
+    python examples/modules_and_functions.py
 
 ## Public API
 
@@ -445,7 +452,7 @@ Run this file to see both outputs:
 - 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.
+You can also pass any stdlib or third-party module — same `modules_and_functions.py` shows it.
 
 ```python
 import pathlib
@@ -494,6 +501,15 @@ operating systems.
 
 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.
 
+You can also pass a function or method directly — `agent_help()` renders the signature, full docstring, and usage rules. The output is close to `help()` for a single callable; the bigger wins are still on classes and modules.
+
+```python
+import pathlib
+from agent_readable import agent_help
+
+print(agent_help(pathlib.Path.read_text))
+```
+
 ```python
 import sys
 
@@ -515,9 +531,13 @@ python -m agent_readable agent_readable:AgentReadableMixin
 
 # Any module
 python -m agent_readable pathlib
+
+# A function or method
+python -m agent_readable json:dumps
+python -m agent_readable pathlib:Path.read_text
 ```
 
-Outputs agent-oriented documentation for the given class or module to stdout.
+Outputs agent-oriented documentation for the given class, module, function, or method to stdout.
 
 ## FAQ
 
@@ -575,7 +595,7 @@ Classes that define a `@classmethod` named `__agent_help__` returning a `str` ar
 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"                                        |

{agent_readable-0.1.0 → agent_readable-0.1.1}/README.md

@@ -2,6 +2,13 @@
 
 A lightweight Python protocol for exposing agent-oriented documentation from classes and modules.
 
+<!-- markdownlint-disable MD033 -->
+<p align="center">
+  <strong><code>logging.Logger</code> compared with <code>agent_help()</code> and <code>help()</code></strong><br>
+  <img src="docs/agent_help_vs_help.gif" alt="agent_help vs help">
+</p>
+<!-- markdownlint-enable MD033 -->
+
 ## 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."*
@@ -378,9 +385,9 @@ Instances of the Logger class represent a single logging channel. A
 
 No mixin, no duck-typing — just pass any class to `agent_help()`.
 
-## Example 5: Modules
+## Example 5: Modules, functions, and methods
 
-`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).
+`agent_help()` also works on modules — it generates a summary with the module docstring, public functions, and classes. Full example: [`examples/modules_and_functions.py`](examples/modules_and_functions.py).
 
 ```python
 import sys
@@ -403,7 +410,7 @@ Demonstrates both shapes of module support:
   2. A stdlib module (pathlib).
 
 Run this file to see both outputs:
-    python examples/module_support.py
+    python examples/modules_and_functions.py
 
 ## Public API
 
@@ -419,7 +426,7 @@ Run this file to see both outputs:
 - 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.
+You can also pass any stdlib or third-party module — same `modules_and_functions.py` shows it.
 
 ```python
 import pathlib
@@ -468,6 +475,15 @@ operating systems.
 
 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.
 
+You can also pass a function or method directly — `agent_help()` renders the signature, full docstring, and usage rules. The output is close to `help()` for a single callable; the bigger wins are still on classes and modules.
+
+```python
+import pathlib
+from agent_readable import agent_help
+
+print(agent_help(pathlib.Path.read_text))
+```
+
 ```python
 import sys
 
@@ -489,9 +505,13 @@ python -m agent_readable agent_readable:AgentReadableMixin
 
 # Any module
 python -m agent_readable pathlib
+
+# A function or method
+python -m agent_readable json:dumps
+python -m agent_readable pathlib:Path.read_text
 ```
 
-Outputs agent-oriented documentation for the given class or module to stdout.
+Outputs agent-oriented documentation for the given class, module, function, or method to stdout.
 
 ## FAQ
 
@@ -549,7 +569,7 @@ Classes that define a `@classmethod` named `__agent_help__` returning a `str` ar
 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"                                        |

agent_readable-0.1.0/examples/module_support.py → agent_readable-0.1.1/examples/modules_and_functions.py

@@ -1,12 +1,14 @@
 """
-Example: Using agent_help() on modules.
+Example: Using agent_help() on modules, functions, and methods.
 
-Demonstrates both shapes of module support:
+Demonstrates non-class targets:
   1. A custom module (this file itself).
   2. A stdlib module (pathlib).
+  3. A function (connect, defined below).
+  4. A method (Query.execute, defined below).
 
-Run this file to see both outputs:
-    python examples/module_support.py
+Run this file to see all outputs:
+    python examples/modules_and_functions.py
 """
 
 import os
@@ -47,3 +49,19 @@ if __name__ == "__main__":
     print("=== agent_help(pathlib) — stdlib module ===")
     print()
     print(agent_help(pathlib))
+
+    print()
+    print("=" * 72)
+    print()
+
+    print("=== agent_help(connect) — function ===")
+    print()
+    print(agent_help(connect))
+
+    print()
+    print("=" * 72)
+    print()
+
+    print("=== agent_help(Query.execute) — method ===")
+    print()
+    print(agent_help(Query.execute))

{agent_readable-0.1.0 → agent_readable-0.1.1}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-readable"
-version = "0.1.0"
-description = "A lightweight protocol for exposing agent-oriented documentation from Python classes and modules"
+version = "0.1.1"
+description = "A lightweight Python protocol for agent-oriented documentation"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"

{agent_readable-0.1.0 → agent_readable-0.1.1}/src/agent_readable/__main__.py

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

{agent_readable-0.1.0 → agent_readable-0.1.1}/src/agent_readable/_protocol.py

@@ -66,7 +66,7 @@ class AgentReadableMixin:
 
 def agent_help(obj: Any) -> str:
     """
-    Return agent-oriented help for a class, instance, or module.
+    Return agent-oriented help for a class, instance, module, function, or method.
 
     Dispatch for classes/instances:
 
@@ -89,6 +89,11 @@ def agent_help(obj: Any) -> str:
     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.
+
+    For functions and methods (anything ``inspect.isroutine`` accepts): an
+    ``__agent_help__`` attribute on the routine — callable or string — is used
+    directly if present; otherwise ``_function_doc()`` renders signature, full
+    docstring, and agent usage rules.
     """
     if inspect.ismodule(obj):
         fn = getattr(obj, "__agent_help__", None)
@@ -104,6 +109,20 @@ def agent_help(obj: Any) -> str:
             return fn
         return _module_doc(obj)
 
+    if inspect.isroutine(obj):
+        override = getattr(obj, "__agent_help__", None)
+        if callable(override):
+            try:
+                result = override()
+                if isinstance(result, str):
+                    return result
+                return str(result)
+            except Exception:
+                pass
+        if isinstance(override, str):
+            return override
+        return _function_doc(obj)
+
     target = obj if inspect.isclass(obj) else obj.__class__
 
     fn = getattr(target, "__agent_help__", None)
@@ -183,6 +202,41 @@ def _collect_module_api(module: types.ModuleType) -> list[str]:
     return lines
 
 
+def _function_doc(fn: Any) -> str:
+    """Generate compact Markdown documentation for a function or method."""
+    parts: list[str] = []
+
+    short_name = getattr(fn, "__name__", None) or "function"
+    display_name = getattr(fn, "__qualname__", None) or short_name
+    parts.append(f"# {display_name}")
+    parts.append("")
+
+    sig = _safe_signature(fn)
+    parts.append("## Signature")
+    parts.append("")
+    parts.append("```python")
+    parts.append(f"{short_name}{sig}")
+    parts.append("```")
+    parts.append("")
+
+    doc = inspect.getdoc(fn)
+    if doc:
+        parts.append("## Purpose")
+        parts.append("")
+        parts.append(doc)
+        parts.append("")
+
+    parts.append("## Agent usage rules")
+    parts.append("")
+    parts.append("- Call with the documented signature.")
+    parts.append("- Do not invent unsupported behavior.")
+    parts.append(
+        "- If usage is ambiguous, prefer the simplest documented usage pattern."
+    )
+
+    return "\n".join(parts)
+
+
 def _base_agent_doc(cls: type) -> str:
     """
     Generate compact Markdown documentation for AI coding agents.

{agent_readable-0.1.0 → agent_readable-0.1.1}/tests/test_cli.py

@@ -71,9 +71,26 @@ def test_cli_nonexistent_attribute():
         _run_main("tests.test_cli:NonExistent")
 
 
-def test_cli_non_class_target():
-    with pytest.raises(TypeError, match="expected a class or module"):
-        _run_main("agent_readable:agent_help")
+def test_cli_function_target(capsys):
+    code = _run_main("agent_readable:agent_help")
+    assert code == 0
+    out = capsys.readouterr().out
+    assert "agent_help" in out
+    assert "## Signature" in out
+
+
+def test_cli_method_target(capsys):
+    code = _run_main("tests.test_cli:Cache.get")
+    assert code == 0
+    out = capsys.readouterr().out
+    assert "Cache.get" in out
+    assert "## Signature" in out
+    assert "Retrieve a value by key." in out
+
+
+def test_cli_invalid_target_type():
+    with pytest.raises(TypeError, match="expected a class, module, function"):
+        _run_main("agent_readable:__version__")
 
 
 def test_cli_module(capsys):

{agent_readable-0.1.0 → agent_readable-0.1.1}/tests/test_protocol.py

@@ -584,3 +584,108 @@ def test_agent_help_module_invalid_attr_falls_back():
     result = agent_help(mod)
     assert "# mymod" in result
     assert "Fallback doc." in result
+
+
+# -- Function / method tests -------------------------------------------------
+
+
+def test_agent_help_function_basic():
+    def greet(name: str) -> str:
+        """Say hello to someone."""
+        return f"Hello, {name}"
+
+    result = agent_help(greet)
+    assert result.startswith("#") and "greet" in result.splitlines()[0]
+    assert "## Signature" in result
+    assert "greet(name: str) -> str" in result
+    assert "## Purpose" in result
+    assert "Say hello to someone." in result
+    assert "## Agent usage rules" in result
+
+
+def test_agent_help_unbound_method_keeps_self():
+    class Pool:
+        def rotated(self, n: int) -> "Pool":
+            """Rotate the pool by n positions."""
+            return self
+
+    result = agent_help(Pool.rotated)
+    assert "Pool.rotated" in result.splitlines()[0]
+    assert "rotated(self, n: int)" in result
+    assert "Rotate the pool by n positions." in result
+
+
+def test_agent_help_bound_method_strips_self():
+    class Pool:
+        def rotated(self, n: int) -> "Pool":
+            """Rotate the pool by n positions."""
+            return self
+
+    result = agent_help(Pool().rotated)
+    assert "rotated(n: int)" in result
+    assert "self" not in result.split("## Signature", 1)[1].split("##", 1)[0]
+
+
+def test_agent_help_classmethod_strips_cls():
+    class Pool:
+        @classmethod
+        def of(cls, n: int) -> "Pool":
+            """Construct a pool of size n."""
+            return cls()
+
+    result = agent_help(Pool.of)
+    assert "of(n: int)" in result
+    assert "Construct a pool of size n." in result
+
+
+def test_agent_help_function_without_docstring():
+    def f(x: int) -> int:
+        return x
+
+    result = agent_help(f)
+    assert result.startswith("#") and "f" in result.splitlines()[0]
+    assert "## Purpose" not in result
+    assert "## Agent usage rules" in result
+
+
+def test_agent_help_function_custom_callable_override():
+    def f():
+        """Auto doc."""
+
+    f.__agent_help__ = lambda: "Custom function help."
+    assert agent_help(f) == "Custom function help."
+
+
+def test_agent_help_function_custom_string_override():
+    def f():
+        """Auto doc."""
+
+    f.__agent_help__ = "String function help."
+    assert agent_help(f) == "String function help."
+
+
+def test_agent_help_function_non_string_return():
+    def f():
+        """Auto doc."""
+
+    f.__agent_help__ = lambda: 99
+    assert agent_help(f) == "99"
+
+
+def test_agent_help_function_override_exception_falls_back():
+    def f():
+        """Fallback doc."""
+
+    def boom():
+        raise RuntimeError("boom")
+
+    f.__agent_help__ = boom
+    result = agent_help(f)
+    assert "Fallback doc." in result
+    assert "## Signature" in result
+
+
+def test_agent_help_builtin_function():
+    result = agent_help(len)
+    assert "# len" in result
+    assert "## Signature" in result