[Convenience PR / branch: all of the docs / all of YM's changes] #787
Conversation
|
Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits. |
ym-han
force-pushed
the
all-ym-changes
branch
from
f4d9740 to
cdc359d
Compare
Greptile OverviewGreetile SummaryThis pull request represents a comprehensive documentation overhaul for the DimensionalOS (DimOS) robotics framework. The changes transform a technically functional but under-documented codebase into a well-documented library with extensive API documentation, conceptual guides, and interactive tutorials. The PR adds a complete MkDocs documentation system with Material theme, including structured navigation across Home, Quickstart, Tutorials, Concepts, and API Reference sections. Key additions include comprehensive docstrings using the The documentation effort covers the entire framework architecture, from low-level transport abstractions and module coordination to high-level agent orchestration and skill creation patterns. This represents a significant improvement in developer experience and accessibility for the robotics framework that integrates LLM-based reasoning with distributed robotic systems. Important Files Changed
Confidence score: 4/5
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
There was a problem hiding this comment.
Additional Comments (1)
-
dimos/core/transport.py, line 81 (link)syntax: duplicate
T = TypeVar("T")definition - line 66 already defines this
41 files reviewed, 17 comments
|
|
||
| - :material-robot: **Agents** | ||
|
|
||
| --- |
There was a problem hiding this comment.
style: Extra space indentation - should align with line 15 for consistency
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
| agent_transport: Annotated[ | ||
| type[PubSub], | ||
| Doc( | ||
| """Transport class for publishing agent messages. Must be a PubSub subclass that | ||
| can be instantiated with no arguments. Used for observability (e.g., by the | ||
| `agentspy` CLI tool).""" | ||
| ), | ||
| ] = lcm.PickleLCM # type: ignore[type-arg] |
There was a problem hiding this comment.
logic: The type annotation allows None but the default is a concrete class - this could cause type checking inconsistencies.
ym-han
force-pushed
the
all-ym-changes
branch
8 times, most recently
from
5892809 to
a30d4fe
Compare
leshy
left a comment
leshy
left a comment
There was a problem hiding this comment.
totally my notes while scrolling through the docs, will do more
|
|
||
| **TODO:** Stash will be writing the intro to DimOS | ||
|
|
||
| The framework enables neurosymbolic orchestration of Agents as generalized spatial reasoners/planners and Robot state/action primitives as functions. |
There was a problem hiding this comment.
this is really intense and flowery marketing language, I don't understand what it means.
I'd call it just framework (not os!) for general robotics
| ``` | ||
| <!-- TODO: Check what the installation directions should be, post-release; hopefully it will be this easy after the library gets published --> | ||
|
|
||
| ## Define a skill |
There was a problem hiding this comment.
imo we are too proud of LLMs and agents and they are too much at our forefront, I have langchain, I can write my own agent integration in a day, I don't care about this when looking into robotics frameworks. I want to see robotics specific capabilities here
I also don't care to learn about the module system before I see actual capabilities that I can use (that I cannot write myself in a few days) AFTER the capabilities are demonstrated I might care to learn about the module system if I have to for my usecase
so I want mapping, navigation, data transfer, viewing/control UI, etc for my robot.
IMO we should ultra bias this quickstart towards a few solid platform(s) we support, split it in a few parts immediately, you choose general/sim/go2/g1 and give people something tangible they can run quickly
| llm_agent(system_prompt="You're a friendly robot. Use greet when asked to say hello."), | ||
| ) | ||
| .global_config(n_dask_workers=1) | ||
| .build() |
There was a problem hiding this comment.
I'm scrolling to see a description or pictures or videos of what I'm reading about and deploying, before reading any code. I don't care what blueprints are at this stage
| ``` | ||
|
|
||
| ``` {title="Output"} | ||
| Hello! How are you doing today? |
There was a problem hiding this comment.
oh it's just a chat agent? I can hook into openai myself I don't care about chat agents at this point
| > [!WARNING] | ||
| > **Don't use both `@skill` and `@rpc` decorators on a single method** - The `@skill` wrapper can't be pickled for LCM transport. Use `@skill()` for agent tools, `@rpc` for module-to-module calls. | ||
| ## Related concepts |
There was a problem hiding this comment.
Ideally at the end of this I have a small piece of code I can run and see this working, demonstrating all skill types in something simple I can play with - I'd suggest our webcam agent experiment. ideally with live audio I/O
Actually first I want to run this, see the value, then maybe I'll read the rest
(reducers, passive/active skills etc)
ym-han
force-pushed
the
all-ym-changes
branch
5 times, most recently
from
f979707 to
abaa1a5
Compare
…for Agents2 reference
cleanup skills
…gent and two sub-agents)
…Add griffe_typingdoc for PEP 727 docs to mkdocs.yml. Add `annotated-doc` for documenting parameters etc in an inline fashion doc type
…d module docstring for blueprints.py
…kill/coordinator.py`
ym-han
force-pushed
the
all-ym-changes
branch
2 times, most recently
from
6440ebb to
9f0ee75
Compare
…fix for AgentSpec was applied in a different commit)
…ation_module.py` and add a bit more detail
ym-han
force-pushed
the
all-ym-changes
branch
from
612c2cb to
40e528b
Compare
…e.g. `AstarPlanner` class docstring)
ym-han
force-pushed
the
all-ym-changes
branch
from
40e528b to
f1d7967
Compare
This is a convenience PR that collects all the changes. When actually reviewing, though, it'd probably be easier to review the constituent PRs.
To understand the dependency structure of the PRs, see https://gist.github.com/ym-han/1eefc2057ffd02428ac3405821959768
To get a quick sense for what docs have been done and what else is left, see #736 (comment) (please do read this comment first).
How to see the docs
First, make sure you've installed the docs deps:
Local Development Server
To start a local server with hot reload:
mkdocs serve # Then open <http://127.0.0.1:8000/> in your browser.Build Static Site
To build the static documentation site:
The output (which includes the various
llm.txes) will be in thesite/directory.See also the note in docs/development.md on marimo notebooks.
What needs to get added to CI
This was mentioned in the comment, but just in case:
xdoctestDepending on the docs platform you go with, you might also need to add CI checks to make sure the links work etc.
Misc resources
Doc site packages
Ivan was asking, so: for reference, the non-Mintlify docs sites solutions I'm aware of include:
Unfortunately, I don't know which of these would be most suitable for you. But the Zensical stuff does suggest that mkdocs isn't a good long-term solution (I went with mkdocs initially just because it's a common choice; hadn't known then that it didn't seem well-maintaned).