docs: add and improve numpy-style docstrings across entire codebase

[royerloic]

Summary

• Added and improved numpy-style docstrings across 125+ files in all subsystems
• Fixed pre-existing copy-paste errors, typos, and misleading messages discovered during review
• Two rounds of thorough diff review ensured docstring accuracy against actual code behavior

Commits

1. docs: add and improve numpy-style docstrings across entire codebase — Module-level docstrings, class/method/function docstrings with Parameters/Returns/Raises sections, standardised to numpy format (125 files)
2. docs: improve base_api.py docstring formatting to numpy style — Reformatted all ~19 method docstrings in base_api.py
3. fix: correct copy-paste errors, typos, and misleading messages — Fixed 7 pre-existing bugs:
   • default_api.py: comments saying "video" in document methods
   • media_action.py: validation messages saying "Object" instead of "Action"
   • media_table.py: error message referencing "dataframe" instead of "table"
   • process_response.py: variable typo processed_reponse to processed_response
   • ollama_api.py: comment typo "hat" to "that"
   • list_models.py: comment typo "ls" to "list"
   • ffmpeg_utils.py: comment typo "a.k_dict.a." to "a.k.a."
4. docs: fix inaccurate docstrings found during review — Fixed 5 issues found by diff review:
   • print_api_callbacks.py: removed false claims about conditional printing
   • default_api.py generate_text: clarified base vs subclass return behavior
   • default_api.py describe_image: fixed return type to Optional[str]
   • anthropic_api.py _uses_adaptive_thinking: fixed parenthetical about suffix stripping
   • ollama_api.py embed_texts: corrected "PCA" to "deterministic random projection"
5. fix: correct expected error messages in test_action.py — Updated tests to match the corrected "Action" validation messages

Scope

Subsystem	Files
agent/ (core, tools, augmentations, messages, actions)	~26 files
apis/ (core, providers: openai, anthropic, google, ollama)	~36 files
media/ (core, types, conversion)	~29 files
utils/	~25 files
tools/, remote/, workflow/, ressources/	~9 files

Stats

• ~4,600 lines added, ~250 lines removed across 125+ files
• All files pass py_compile syntax verification
• Code formatted with black and isort
• Two rounds of automated diff review (8 agents total) verified accuracy

Test plan

• All modified files pass Python syntax verification (py_compile)
• Code formatted with black and isort
• Diff reviewed by 8 specialized review agents across all subsystems
• All inaccuracies found during review have been fixed
• Test suite updated for changed validation messages (test_action.py)

Generated with Claude Code