API Reference Generator

Auto-generate comprehensive API documentation

The praisonai docs api-md command generates a comprehensive API reference document (api.md) at the repository root, covering all public exports from praisonaiagents, praisonai, CLI commands, and TypeScript packages.

Quick Start

# Generate/update api.md
praisonai docs api-md

# Check if api.md is up to date (for CI)
praisonai docs api-md --check

# Print to stdout
praisonai docs api-md --stdout

Commands

Generate API Reference

praisonai docs api-md

Generates api.md at the repository root with all public API surfaces.

Expected Output:

✓ Generated /path/to/repo/api.md

Check Mode

praisonai docs api-md --check

Verifies that api.md is up to date. Exits with code 1 if outdated.

Use Case: CI/CD pipelines to ensure API docs are current.

Expected Output (when current):

✓ /path/to/repo/api.md is up to date

Expected Output (when outdated):

✗ api.md is out of date. Run: praisonai docs api-md --write

Print to Stdout

praisonai docs api-md --stdout

Prints the generated API reference to stdout instead of writing to file.

Use Case: Preview changes or pipe to other tools.

Generated Content

The api.md file includes:

Python Core SDK (praisonaiagents)

• Agents - Agent, Agents, AutoAgents, DeepResearchAgent, etc.
• Tools - BaseTool, FunctionTool, MCP, Tools
• Workflows - Workflow, Task, Pipeline
• Memory - Memory, Session, Context
• Knowledge - Knowledge, RAG, Chunking
• Other - Handoff, Guardrails, Skills, Telemetry

Python Wrapper (praisonai)

• PraisonAI, Deploy, Recipe
• Re-exported praisonaiagents symbols

CLI Commands

All praisonai CLI commands with their subcommands and flags.

TypeScript SDK (praisonai-ts)

All exported classes, types, and functions from the TypeScript package.

Output Format

The generated api.md follows OpenAI SDK-style formatting:

# PraisonAI API Reference

## Agents

Types:
```python
from praisonaiagents import Agent, AgentTeam

Methods:

• Agent.start(prompt: str)
• Agent.chat(message: str)

## Discovery Algorithm

The generator uses AST-based static analysis to discover symbols:

1. **Parse `__all__`** - Respects explicit public API declarations
2. **Lazy-loaded symbols** - Extracts symbols from `__getattr__` functions
3. **Direct imports** - Tracks `from X import Y` statements
4. **Method extraction** - Discovers class methods via AST
5. **CLI commands** - Parses Typer command definitions
6. **TypeScript exports** - Regex-based export parsing

## Performance

- **Import time:** ~30ms (stdlib only: ast, re, sys, pathlib)
- **No heavy dependencies** - No doc generation libraries
- **Lazy loading** - Generator only loaded when explicitly called
- **Zero runtime impact** - Not loaded during normal package usage

## CI/CD Integration

Add to your CI pipeline to ensure API docs stay current:

```yaml
# .github/workflows/ci.yml
- name: Check API docs
  run: praisonai docs api-md --check

Contributing

When adding new public APIs:

1. Add the symbol to __all__ in the relevant __init__.py
2. Run praisonai docs api-md to regenerate
3. Commit both code changes and updated api.md

Python API

from praisonai._dev.api_md import generate_api_md
from pathlib import Path

# Generate api.md
exit_code = generate_api_md(
    repo_root=Path.cwd(),
    output_path=Path("api.md"),
    check=False,
    stdout=False
)

# Check mode
exit_code = generate_api_md(
    repo_root=Path.cwd(),
    output_path=Path("api.md"),
    check=True
)
# Returns 0 if current, 1 if outdated

Related

• CLI Reference - Complete CLI command tree
• Docs Management - Project documentation
• Examples - Code examples validation