docs: Documentation for event-based models#117
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hello @toby-coleman, 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!
Summary of Changes
This pull request focuses on enhancing the documentation for the Plugboard library, specifically adding a tutorial for event-based process models. It also includes minor improvements to the README and adds tags and a topic index to the documentation for better navigation. The event-based model tutorial introduces the concept of event-driven models within Plugboard, demonstrating how data can be passed between components based on defined triggers.
Highlights
- Documentation: Adds a complete tutorial for event-based process models, explaining how to define events, build components to create and consume events, and put it all together in a Plugboard process.
- Navigation: Implements tags and a topic index in the documentation to improve navigation and make it easier for users to find specific information.
- README Updates: Includes minor fixes and improvements to the README file, such as adding detailed logging to the list of Plugboard's capabilities and updating the documentation link.
Changelog
Click here to see the changelog
- README.md
- Added 'Detailed logging' to the list of Plugboard capabilities.
- Updated the documentation site link to point to the 'latest' version.
- docs/examples/tutorials/.meta.yml
- Added tags for the tutorial.
- docs/examples/tutorials/event-driven-models.md
- Created a new tutorial for event-driven models, including explanations, code snippets, and a diagram of the model.
- Added frontmatter tags for events.
- docs/examples/tutorials/more-components.md
- Added frontmatter tags for logging, llm, and io.
- Added an info section about logging with structlog.
- docs/examples/tutorials/running-in-parallel.md
- Added frontmatter tags for ray.
- docs/usage/key-concepts.md
- Updated the documentation to refer to
Eventas [Event][plugboard.events.Event]. - Updated the documentation to refer to
Connectoras [Connector][plugboard.connector.Connector].
- Updated the documentation to refer to
- docs/usage/topics.md
- Created a topic index page to improve documentation navigation.
- examples/demos/llm/.meta.yml
- Added tags for llm.
- examples/demos/llm/002_bluesky_websocket/.meta.yml
- Added tags for io and streaming.
- examples/demos/physics-models/.meta.yml
- Added tags for physics-models.
- examples/tutorials/003_more_components/hello_llm.py
- Changed the example description from 'Simple hello world example' to 'Simple LLM example'.
- Added error logging for weather API queries using structlog.
- examples/tutorials/005_events/.gitignore
- Added *.csv to the .gitignore file.
- examples/tutorials/005_events/hello_events.py
- Created a new Python file containing the event-based model example, including event definitions, component implementations, and the main function to run the model.
- examples/tutorials/005_events/model.yaml
- Created a new YAML file defining the event-based model.
- mkdocs.yaml
- Added 'meta' and 'tags' plugins.
- Added 'Topics' to the navigation menu.
Using Gemini Code Assist
The 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 in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.
| Feature | Command | Description |
|---|---|---|
| Code Review | /gemini review |
Performs a code review for the current pull request in its current state. |
| Pull Request Summary | /gemini summary |
Provides a summary of the current pull request in its current state. |
| Comment | @gemini-code-assist | Responds in comments when explicitly tagged, both in issue comments and review comments. |
| Help | /gemini help |
Displays a list of available commands. |
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 .gemini/ folder in the base of the repository. Detailed instructions can be found here.
Limitations & Feedback
Gemini Code Assist is currently in preview and 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 to provide feedback.
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.
Did you know?
The Mermaid diagramming tool, used in the event-driven model documentation, was initially created by Knut Sveidqvist in 2014 to simplify documentation.
Footnotes
-
Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩
There was a problem hiding this comment.
Code Review
The pull request adds documentation for event-based process models, improves documentation navigation with tags and a topic index, and includes minor fixes to the README. The changes look good overall, with a well-structured tutorial and helpful additions to the documentation.
Merge Readiness
The pull request appears to be in good shape for merging. The addition of documentation for event-based models is a valuable contribution, and the improvements to navigation enhance the user experience. I am unable to directly approve the pull request, and recommend that others review and approve this code before merging.
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
toby-coleman
changed the title
|
@chrisk314 there are a few bits in here other than the event-based examples that would be good to merge. I'll cherry-pick them into a separate PR tomorrow and merge them in. |
# Summary Various improvements to the docs, including topic tags. Migrated from #117. # Changes * Adds tags and a topic index to the docs for improved navigation. * Minor fixes and improvements to the README. * Small fix to the logger code to allow it to serialise types not supported by `msgspec`, e.g. Pydantic objects.
# Summary Various improvements to the docs, including topic tags. Migrated from #117. # Changes * Adds tags and a topic index to the docs for improved navigation. * Minor fixes and improvements to the README. * Small fix to the logger code to allow it to serialise types not supported by `msgspec`, e.g. Pydantic objects.
chrisk314
force-pushed
the
main
branch
2 times, most recently
from
c5dd519 to
daf3ac4
Compare
|
Benchmark comparison for |
|
Benchmark comparison for |
|
@chrisk314 this PR is fixed up and running correctly with the new event code. One change I have noticed is a difference in mixed event/stepping components. For example: This component is event-driven only, and its step method will be called only after an event. Previously, step would have been called at every step of the model. class MyComponent(Component):
io = IOController(input_events=[SomeEvent])
async def step(self) -> None:
self._logger.info("Step called")
@SomeEvent.handler
async def my_handler(self, event: SomeEvent) -> None:
self._logger.info("Event handled", data=event.data)This component has both an input and an event, and its step method is called on every step of the model. class MyComponent(Component):
io = IOController(inputs=["some_input"], input_events=[SomeEvent])
async def step(self) -> None:
self._logger.info("Step called")
@SomeEvent.handler
async def my_handler(self, event: SomeEvent) -> None:
self._logger.info("Event handled", data=event.data)I think the new behaviour is quite useful in many circumstances, but also means that if the user does want step called at every process step, then they need to include a dummy input to the component to make it look like the second example. Do you think we should document like this, or have some way of configuring the two different behaviours without resorting to dummy inputs? |
|
Benchmark comparison for |
|
Benchmark comparison for |
1 participant
Summary
Adds documentation for event-based process models.
Changes