Doctorial

Doctorial is a Python CLI that turns API documentation into framework-specific tutorials and reusable example bundles.

It parses OpenAPI, markdown, or remote docs, suggests practical scenarios, and generates bundles for targets like LangChain, Codex, Claude Code, MCP, and related tooling.

What It Does

• Parse API docs into a normalized API profile
• Suggest tutorial scenarios for a chosen framework
• Generate tutorial bundles with markdown, notebooks, and framework-specific files
• Run locally as a CLI with no web app or service layer

Features

• Support built-in and custom framework targets
• Work with local files or remote docs
• Export reusable tutorial assets for developer workflows

Built-in Targets

• Claude Code
• Codex
• OpenClaw
• LangChain
• OpenAI Agents SDK
• CrewAI
• Google ADK
• PydanticAI
• Mastra
• LlamaIndex
• MCP

Custom framework targets are also supported.

Installation

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
cp .env.example .env

Doctorial automatically loads .env and .env.local from the repository root.

Quick Start

Generate a LangChain tutorial bundle from the OpenJobs AI API docs:

doctorial generate \
  --doc-url "https://platform.openjobs-ai.com/docs/api" \
  --framework langchain \
  --scenario "Build a LangChain recruiting assistant that uses candidate search, profile lookup, grading, and analytics to shortlist strong candidates." \
  --output ./doctorial-output/openjobs-langchain

Typical output includes files like:

doctorial-output/openjobs-langchain/
  tutorial.md
  tutorial.ipynb
  README.md
  requirements.txt
  ...

Other useful commands:

List supported frameworks:

doctorial frameworks list

Parse an API spec:

doctorial parse --doc-url "https://platform.openjobs-ai.com/docs/api"

Suggest OpenJobs AI tutorial scenarios for LangChain:

doctorial suggest --doc-url "https://platform.openjobs-ai.com/docs/api" --framework langchain

Generate the OpenJobs AI bundle:

doctorial generate \
  --doc-url "https://platform.openjobs-ai.com/docs/api" \
  --framework langchain \
  --scenario "Build a LangChain recruiting assistant that uses candidate search, profile lookup, grading, and analytics to shortlist strong candidates." \
  --output ./doctorial-output/openjobs-langchain

Run tests:

python -m unittest discover -s tests

Commands

doctorial frameworks list
doctorial frameworks info codex
doctorial parse --doc-url "https://platform.openjobs-ai.com/docs/api"
doctorial suggest --doc-url "https://platform.openjobs-ai.com/docs/api" --framework langchain
doctorial generate --doc-url "https://platform.openjobs-ai.com/docs/api" --framework langchain --scenario "Build a LangChain recruiting assistant that uses candidate search, profile lookup, grading, and analytics to shortlist strong candidates." --output ./doctorial-output/openjobs-langchain

Environment Variables

DOCTORIAL_LLM_PROVIDER=openrouter
DOCTORIAL_LLM_API_KEY=...
DOCTORIAL_LLM_MODEL=openai/gpt-4.1-mini
DOCTORIAL_LLM_BASE_URL=

# Backward-compatible provider-specific env vars still work:
OPENROUTER_API_KEY=...
OPENROUTER_MODEL=openai/gpt-4.1-mini
OPENAI_API_KEY=...
OPENAI_MODEL=gpt-4.1-mini
ANTHROPIC_API_KEY=...
ANTHROPIC_MODEL=claude-3-5-sonnet-latest
GEMINI_API_KEY=...
GEMINI_MODEL=gemini-2.5-pro

TAVILY_API_KEY=...
DOCTORIAL_HOME=$HOME/.doctorial
DOCTORIAL_TRUST_ENV=1

Supported providers:

• openrouter
• openai
• anthropic
• gemini
• openai-compatible

Repository Layout

• src/doctorial: package source
• tests: unit tests and fixtures
• .env.example: local configuration template

Contributing

Start with CONTRIBUTING.md. For vulnerabilities or sensitive reports, follow SECURITY.md.

License

This project is licensed under the MIT License.