Feat(sdk, docs): Adding auto-generated python sdk reference#2283
Open
Feat(sdk, docs): Adding auto-generated python sdk reference#2283
Conversation
added 6 commits
March 4, 2026 11:51
Signed-off-by: Jan Jeliga <jan.jeliga@gmail.com>
Signed-off-by: Jan Jeliga <jan.jeliga@gmail.com>
Signed-off-by: Jan Jeliga <jan.jeliga@gmail.com>
Signed-off-by: Jan Jeliga <jan.jeliga@gmail.com>
dosubot
bot
added
the
size:XXL
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull request overview
Adds auto-generated Python SDK reference documentation and supporting tooling/config updates.
Changes:
- Introduces many generated MDX reference pages under
docs/development/reference/python-sdk/**. - Adds Jinja templates to generate SDK docs pages.
- Updates the Python SDK package (dependencies + a couple of typing/formatting tweaks) and contributor documentation to reflect the new docs workflow.
Reviewed changes
Copilot reviewed 299 out of 335 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/development/reference/python-sdk/** | Adds auto-generated Python SDK reference pages (MDX) |
| apps/agentstack-sdk-py/docs/templates/overview.mdx.j2 | Template for generating the SDK overview page |
| apps/agentstack-sdk-py/docs/templates/function.mdx.j2 | Template for generating function reference pages |
| apps/agentstack-sdk-py/pyproject.toml | Adds doc-generation dependencies |
| apps/agentstack-sdk-py/src/agentstack_sdk/platform/client.py | Adds explicit callable type annotations for platform client context helpers |
| apps/agentstack-sdk-py/src/agentstack_sdk/util/pydantic.py | Minor formatting changes in compatibility monkey-patching |
| apps/agentstack-sdk-py/src/agentstack_sdk/a2a/extensions/tools/exceptions.py | Minor formatting change (blank line) |
| CONTRIBUTING.md | Updates contributor guidance for generated reference docs |
Comments suppressed due to low confidence (1)
apps/agentstack-sdk-py/src/agentstack_sdk/platform/client.py:1
- The new
Callable[..., ...]annotations lose the call signature ofset_platform_client, andwrap_contextis already set up to preserve signatures viaParamSpec. Consider tightening these annotations using a sharedParamSpec/ explicit constructor args so IDEs and type-checkers can surface correct parameters forset_platform_client(...)anduse_platform_client(...).
# Copyright 2025 © BeeAI a Series of LF Projects, LLC
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
apps/agentstack-sdk-py/src/agentstack_sdk/a2a/extensions/tools/exceptions.py
Show resolved
Hide resolved
Contributor
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request implements an automated documentation generation pipeline for the Python SDK. It introduces new scripts and templates that introspect the Python codebase and produce structured Markdown (MDX) reference documentation. This enhancement streamlines the documentation process, ensuring that the SDK reference remains up-to-date with code changes and reduces manual effort. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Changelog
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces a robust mechanism for auto-generating the Python SDK reference documentation. It adds two main scripts: one for introspecting the SDK code using ast and griffe to produce a JSON manifest of the public API, and another for rendering this manifest into MDX files using Jinja2 templates. The process is orchestrated by a new mise task which is well-designed with good error handling and cleanup. The changes also include updates to dependencies and contributor guidelines. This is a significant improvement for documentation maintenance and quality. My review found a minor issue in the updated CONTRIBUTING.md file.
Note: Security Review did not run due to the size of the PR.
Signed-off-by: Jan Jeliga <jan.jeliga@gmail.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 299 out of 336 changed files in this pull request and generated 4 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
.../development/reference/python-sdk/server-store-memory-context-store/InMemoryContextStore.mdx
Show resolved
Hide resolved
tomkis
reviewed
Mar 5, 2026
Collaborator
There was a problem hiding this comment.
Conceptually - have you considered going with e2e markdown generation? I know mintlify uses specifix mdx, but i wonder if the extra mintlify niceness is worth the extra code.
eg. something like https://mkdocstrings.github.io/python/
My reasoning here is that we mostly need the SDK reference for agent consumption anyway - so the extra niceness might not even be worth it.
Contributor
Author
I have tried something very similar but did not go for it because
Also I don't think it should be considered just for agent consumption. It does not make sense to let your agent code something based solely on the reference unless it is extremely well documented. And our package isn't, there are barely any docstrings. Any coding agents will do a much better job after looking at the actual implementation, not docs. |
Signed-off-by: Jan Jeliga <jan.jeliga@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adding auto-generating capability fior python sdk reference
Linked Issues
closes #2133
Documentation
If this PR adds new feature or changes existing. Make sure documentation is adjusted accordingly. If the docs is not needed, please explain why.