You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Restore developer_guides text/prose (rewrites + :orphan: removals + plumbing-prose scrubs)
This branch is the holding area for the developer-guides prose work
while the sibling site-merge integration branch ships a thin
developer-guides surface (main-state plus three structural
compensations — see the site-merge revert commit for details).
Restored on this branch:
- `developer_guides/index.rst`: the marketing-flow-then-docs-scaffold
rewrite (plain title, intro paragraphs naming the reading order,
5-card sphinx_design grid covering Inference pipeline overview /
Config system / Add a new method / Usage patterns / Interactive
serving, a "Where these guides fit" closing block with cross-links
to /quickstart-now-get_started and /api/index, and a :hidden:
toctree of all five sub-pages).
- `:orphan:` removed from `usage_patterns.rst` and
`interactive_serving.rst` so they can sit non-orphan inside the
rewritten index's toctree.
- Plumbing-prose scrubs across the sub-pages (`flashdreams-run` /
`uv` references in narrative prose were taken out and kept only in
code blocks).
PR target: `dev/aidanf/flashdreams-site-merge`. When this branch is
ready, the merge brings the developer-guides text content into the
public-website integration line.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Revert changes related to unused guides
* Revert changes related to unused guides
* Integrate new docs into docs section
* Cleanup
* Cleanup
* Rewrite API/CLI index
* Rename API index
* Consistency of API index title
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: docs/source/developer_guides/config_system.rst
+9-13Lines changed: 9 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,15 +17,15 @@ Config system
17
17
===================================
18
18
19
19
FlashDreams configuration is built around simple, strongly-typed Python ``dataclass`` objects.
20
-
This configuration system is similar to the one employed in `nerfstudio <https://github.com/nerfstudio-project/nerfstudio>`_,
21
-
allowing to easily compose different model components variants and nest configurations to define the complete
20
+
This configuration system is similar to the one employed in `nerfstudio <https://github.com/nerfstudio-project/nerfstudio>`_.
21
+
It allows you to easily plug in different permutations of model components and nest configurations to define the complete
22
22
inference pipeline.
23
23
24
24
Base components
25
25
---------------
26
26
27
-
All configurable components in FlashDreams - such as the encoder, transformer, scheduler, and decoder -
28
-
have a corresponding configuration dataclass in ``flashdreams.infra``.
27
+
All configurable components in FlashDreams (such as the encoder, transformer, scheduler, and decoder)
28
+
have a corresponding configuration dataclass and can be found under ``flashdreams.infra``.
29
29
As outlined in the :doc:`/developer_guides/inference_pipeline_overview`, the main entry point for defining an integration
30
30
is the :class:`~flashdreams.infra.pipeline.StreamInferencePipelineConfig`.
31
31
@@ -57,10 +57,9 @@ A typical pipeline config defines the architecture by composing other config dat
57
57
Creating new configs
58
58
--------------------
59
59
60
-
To create a brand new model component, a corresponding config with the associated parameters to be exposed has to be created.
60
+
If you are interested in creating a brand new model component, you will need to create a corresponding config with the associated parameters you want to expose.
61
61
62
-
To create a new encoder called ``MyEncoder``, a new ``Encoder`` class that extends the base class has to be defined.
63
-
Before the model definition, the actual ``MyEncoderConfig``, which points to the ``MyEncoder`` class, has to be defined using the ``_target`` field.
62
+
Let's say you want to create a new encoder called ``MyEncoder``. You can create a new ``Encoder`` class that extends the base class. Before the model definition, you define the actual ``MyEncoderConfig`` which points to the ``MyEncoder`` class using the ``_target`` field.
64
63
65
64
.. code-block:: python
66
65
@@ -97,9 +96,7 @@ Before the model definition, the actual ``MyEncoderConfig``, which points to the
97
96
defforward(self, input):
98
97
...
99
98
100
-
Alternatively, it's not always required to define a complete configuration from scratch.
101
-
One can use :func:`flashdreams.infra.config.derive_config` to create concise variants from existing configs,
102
-
allowing to inherit the base settings and to only override specific fields:
99
+
Alternatively, you do not always have to write a complete configuration from scratch. You can use :func:`flashdreams.infra.config.derive_config` to create concise variants from existing configs. This allows you to inherit the base settings and only override the specific fields you want to change:
103
100
104
101
.. code-block:: python
105
102
@@ -116,10 +113,9 @@ allowing to inherit the base settings and to only override specific fields:
116
113
Modifying from CLI
117
114
------------------
118
115
119
-
To simply play with the parameters of an existing model without having to specify a new one, one can employ CLI arguments, which are powered by `tyro <https://github.com/brentyi/tyro>`_.
116
+
Often you just want to play with the parameters of an existing model without specifying a new configuration. The command-line interface, powered by `tyro <https://github.com/brentyi/tyro>`_, exposes every nested dataclass field as a flag.
120
117
121
-
Because the FlashDreams configurations are strongly typed dataclasses, ``tyro`` automatically generates a comprehensive command-line interface.
122
-
The ``flashdreams-run`` cli command can be used to dynamically override any nested dataclass field.
118
+
Because configurations are strongly typed dataclasses, ``tyro`` generates the CLI automatically. Each shipped model is a named runner slug; pass any nested field as a flag to override it.
123
119
124
120
For example, to list all existing configurable parameters for a model:
Copy file name to clipboardExpand all lines: docs/source/developer_guides/new_integration.rst
+17-19Lines changed: 17 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,16 +16,16 @@
16
16
Add a new method
17
17
===================================
18
18
19
-
Before starting to add a new method, we highly recommend reading the :doc:`/developer_guides/inference_pipeline_overview` and :doc:`/developer_guides/config_system` pages first to obtain an overview of the system's architecture.
19
+
Before you start adding a new method, we highly recommend reading the :doc:`/developer_guides/inference_pipeline_overview` and :doc:`/developer_guides/config_system` pages first to obtain an overview of the system architecture.
20
20
21
-
FlashDreams aims to offer researchers a codebase that they can utilize to extend and develop novel video and world models. Our vision is for users to establish a *standalone repository* that imports FlashDreams as a dependency and overrides pipeline components (such as encoders, transformers, or decoders) to cater to specific functionality requirements of the new approach. We encourage to maintain methods externally rather than pushing changes directly into the `integrations/ <https://github.com/NVIDIA/flashdreams/tree/main/integrations>`_ directory of this repository.
21
+
FlashDreams aims to offer researchers a codebase that they can utilize to extend and develop novel video and world models. Our vision is for users to establish a *standalone repository* that imports FlashDreams as a dependency and overrides pipeline components (such as encoders, transformers, or decoders) to cater to specific functionality requirements of the new approach. We encourage you to maintain your method externally rather than pushing changes directly into the `integrations/ <https://github.com/NVIDIA/flashdreams/tree/main/integrations>`_ directory of this repository.
22
22
23
-
However, if any new features requires modifications to the core FlashDreams infra or introduce generally useful components (such as the :mod:`TAEHV decoder <flashdreams.recipes.taehv>`), we encourage you to submit a PR to enable others to benefit from them.
23
+
However, if any of your new features require modifications to the core FlashDreams infra or introduce generally useful components (such as the :mod:`TAEHV decoder <flashdreams.recipes.taehv>`), we encourage you to submit a PR to enable others to benefit from them.
24
24
25
25
File structure
26
26
--------------
27
27
28
-
We recommend the following file structure for new methods:
28
+
We recommend the following file structure for your new method:
29
29
30
30
.. code-block:: text
31
31
@@ -41,7 +41,7 @@ We recommend the following file structure for new methods:
41
41
│ └── ...
42
42
└── pyproject.toml
43
43
44
-
Add optional files are only if customization beyond what is available in FlashDreams is required.
44
+
Add optional files only when you need to customize the behavior beyond what is available in FlashDreams.
45
45
Most integrations can use the base :class:`~flashdreams.infra.pipeline.StreamInferencePipeline` directly and only provide model components plus config literals.
46
46
As explained in :doc:`/developer_guides/config_system`, a method typically defines a pipeline config and a runner config.
47
47
The runner handles CLI-facing I/O and runtime loops.
@@ -104,29 +104,27 @@ The runner handles CLI-facing I/O and runtime loops.
104
104
)
105
105
106
106
107
-
Existing integrations under the `integrations/ <https://github.com/NVIDIA/flashdreams/tree/main/integrations>`_ can be used as a minimal guide.
108
-
These folders are simple examples of what mini standalone repositories that depend on FlashDreams look like.
109
-
Examples are often the best way to learn; take a look at the `LingBot-World <https://github.com/NVIDIA/flashdreams/tree/main/integrations/lingbot>`_ and `Self-Forcing <https://github.com/NVIDIA/flashdreams/tree/main/integrations/self_forcing>`_ integrations for good references on how to extend and use FlashDreams in a custom project.
107
+
You can use the existing integrations under the `integrations/ <https://github.com/NVIDIA/flashdreams/tree/main/integrations>`_ directory as a minimal guide. These folders are simple examples of what mini standalone repositories that depend on FlashDreams look like. Examples are often the best way to learn; take a look at the `LingBot-World <https://github.com/NVIDIA/flashdreams/tree/main/integrations/lingbot>`_ and `Self-Forcing <https://github.com/NVIDIA/flashdreams/tree/main/integrations/self_forcing>`_ integrations for good references on how to extend and use FlashDreams in your own projects.
110
108
111
-
Registering methods
112
-
-------------------
109
+
Registering your method
110
+
-----------------------
113
111
114
-
After registering a method one should be able to see it in the CLI helptext and run it, leveraging the existing CLI for complete command line control:
112
+
After registering your method you should be able to see it in the CLI helptext and run it, leveraging the existing CLI for complete command line control:
115
113
116
114
.. code-block:: bash
117
115
118
-
# List all available models, including new ones
116
+
# List all available models, including your new one
119
117
flashdreams-run --help
120
118
121
-
# See configurable parameters for new models
119
+
# See configurable parameters for your new model
122
120
flashdreams-run customized-method --help
123
121
124
122
# Run the new model
125
123
flashdreams-run customized-method --prompt "A beautiful custom generation."
126
124
127
-
In order to extend FlashDreams and register own models, one can package code as a Python package and register it with FlashDreams via an entrypoint in the ``pyproject.toml`` file. FlashDreams will automatically search for all registered runners and will register them to be used by the ``flashdreams-run`` CLI.
125
+
To register your own models, package your code as a Python package and declare a runner entry point in its ``pyproject.toml``. FlashDreams discovers every registered runner at import time and surfaces it through the same command-line interface as the in-tree recipes. There is no central manifest to keep in sync.
128
126
129
-
A ``pyproject.toml`` fileis where the entrypoint to custom methods is specified and additional dependencies are specified. For example:
127
+
Create a ``pyproject.toml`` file. This is where the entrypoint to your method is set and also where you can specify additional dependencies required by your codebase.
130
128
131
129
.. code-block:: toml
132
130
:caption: pyproject.toml
@@ -152,16 +150,16 @@ Finally, run the following to register the method:
152
150
153
151
pip install -e .
154
152
155
-
When developing a new methods they don't always need to be installed as a package. Instead, the ``FLASHDREAMS_RUNNER_CONFIGS`` environment variable can be usedto temporarily register custom custom method.
153
+
When developing a new method, you don't always want to install your code as a package. Instead, you may use the ``FLASHDREAMS_RUNNER_CONFIGS`` environment variable to temporarily register your custom method.
The ``FLASHDREAMS_RUNNER_CONFIGS`` environment variable additionally accepts a function (a zero-arg callable) to temporarily register custom runners if construction has side effects to be deferred until CLI time.
159
+
The ``FLASHDREAMS_RUNNER_CONFIGS`` environment variable additionally accepts a function (a zero-arg callable) to temporarily register your custom runner if construction has side effects you want to defer until CLI time.
162
160
163
161
Adding to the FlashDreams documentation
164
162
---------------------------------------
165
163
166
-
We invite researchers to contribute their own integrations to our official codebase and documentation. More information on how to do this can be found in the repository's `CONTRIBUTING.md <https://github.com/NVIDIA/flashdreams/blob/main/CONTRIBUTING.md>`_.
167
-
See the existing model pages under the `docs/source/models/ <https://github.com/NVIDIA/flashdreams/tree/main/docs/source/models>`_ (e.g., :doc:`/models/self_forcing`) as templates for documenting new methods.
164
+
We invite researchers to contribute their own integrations to our official codebase and documentation. You can find more information on how to do this in the repository's `CONTRIBUTING.md <https://github.com/NVIDIA/flashdreams/blob/main/CONTRIBUTING.md>`_.
165
+
See the existing model pages under the `docs/source/models/ <https://github.com/NVIDIA/flashdreams/tree/main/docs/source/models>`_ directory (e.g., :doc:`/models/self_forcing`) as templates for documenting your new method.
0 commit comments