Praison AI

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

bash
# 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

bash
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

bash
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

bash
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:

markdown
# PraisonAI API Reference

## Agents

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

Methods:

  • <code title=”class Agent”>Agent.<a href=”./src/…”>start</a>(prompt: str)</code>
  • <code title=”class Agent”>Agent.<a href=”./src/…”>chat</a>(message: str)</code>
## 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

python
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