pydantic-ai
pydantic-ai copied to clipboard
pydantic
Add LLM optimized documentation
Enhancement
When using AI coding assistants it is very helpful to have a version of the documentation that is on a single page and optimized for LLMs, usually markdown source seems to be a good idea. There is also llmstxt for this purpose but addresses a wider use case, generally making website content better understandable for LLMs. IMHO both approaches would be great.
Examples
- Jina API docs as single markdown page: https://docs.jina.ai/
- FastHTML docs as llmstxt page: https://docs.fastht.ml/llms-ctx-full.txt
Makes sense, the biggest challenge is rendering the API docs in markdown, see https://github.com/mkdocstrings/mkdocstrings/issues/701.
Something like this?
uvx --with pydantic-ai --with black griffe2md pydantic_ai > docs.md
uvx frogmouth docs.md
I think this isn't particularly optimized for LLMs though :slightly_smiling_face:
@olafgeibig I'd be interested to understand how you're registering the LLM optimised documentation with your LLM?
Oh... I missed your question. I simply store the docs as a single text file and add that file to the context of the coding assistant. i.e. with /read of aider.
Maybe some more insights into the real world use cases from my perspective. I think llmstxt covers both of my use cases. See the directory of sites using llmstxt. There are websites having both, a sitemap (llms-txt) and a full documentation (llms-full.txt)
All docs in a single page
All docs concatenated into a single markdown file. This allows to add the whole documentation into the LLM context. This is great for coding assistants like aider, cursor or windsurf. You can point them to the docs file and then the assistant has got the knowledge to use the framework properly. This is also great when creating complex XML formatted prompts for reasoning LLMs like IndyDevDan's meta-prompt. In this case I would put the whole single-page-docs between <documentation> tags.
LLM sitemap
A markdown file with a sitemap with a short description for each page. This allows a web capable LLM to navigate your site and pull the needed information from it. This is great for agents or LLM clients with web capabilities, e.g. claude desktop app with suitable MCP servers like https://github.com/smithery-ai/community-servers.
@olafgeibig this is solved with: https://github.com/pydantic/pydantic-ai/pull/649.
https://ai.pydantic.dev/llms.txt is now available. Can you please test this and let us know if the current format works? Thanks!
Interesting approach, thanks for the update. I wanted to write a MkDocs plugin that simply concatenates pages (Markdown) together, but it wouldn't handle generated contents (API docs, markdown-exec'd blocks, pymdownx snippets, mkdocs-macros, etc.), like your solution does.
@pawamoy that was my plan originally, but what @petyosi did seemed to work well, so makes sense to start with that.
I followed @petyosi's approach: https://github.com/pawamoy/mkdocs-llmstxt :blush: It goes a bit further, making sure code blocks have the right language, handling mkdocstrings/autorefs stuff, using "ATX" style headings instead of underlined, and formatting the generated Markdown.