donna 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. donna/artifacts/intro.md +39 -0
  2. donna/artifacts/research/specs/report.md +163 -0
  3. donna/artifacts/research/work/research.md +198 -0
  4. donna/artifacts/rfc/specs/request_for_change.md +270 -0
  5. donna/artifacts/rfc/work/create.md +120 -0
  6. donna/artifacts/rfc/work/do.md +109 -0
  7. donna/artifacts/rfc/work/plan.md +68 -0
  8. donna/artifacts/usage/artifacts.md +55 -12
  9. donna/artifacts/usage/cli.md +114 -39
  10. donna/artifacts/usage/worlds.md +8 -2
  11. donna/cli/__main__.py +1 -1
  12. donna/cli/commands/artifacts.py +104 -17
  13. donna/cli/commands/sessions.py +8 -8
  14. donna/cli/commands/workspaces.py +42 -0
  15. donna/cli/errors.py +18 -0
  16. donna/cli/types.py +16 -9
  17. donna/cli/utils.py +2 -2
  18. donna/core/errors.py +1 -11
  19. donna/core/result.py +5 -8
  20. donna/core/utils.py +0 -3
  21. donna/lib/__init__.py +4 -0
  22. donna/lib/sources.py +1 -1
  23. donna/lib/worlds.py +2 -2
  24. donna/machine/action_requests.py +0 -5
  25. donna/machine/artifacts.py +8 -6
  26. donna/machine/primitives.py +5 -5
  27. donna/machine/sessions.py +13 -5
  28. donna/machine/state.py +4 -4
  29. donna/machine/tasks.py +4 -18
  30. donna/machine/templates.py +4 -2
  31. donna/primitives/artifacts/specification.py +13 -2
  32. donna/primitives/artifacts/workflow.py +11 -2
  33. donna/primitives/directives/list.py +86 -0
  34. donna/primitives/directives/view.py +52 -11
  35. donna/primitives/operations/finish_workflow.py +13 -2
  36. donna/primitives/operations/output.py +87 -0
  37. donna/primitives/operations/request_action.py +3 -9
  38. donna/primitives/operations/run_script.py +2 -2
  39. donna/protocol/utils.py +22 -0
  40. donna/workspaces/artifacts.py +238 -0
  41. donna/{world → workspaces}/artifacts_discovery.py +1 -1
  42. donna/{world → workspaces}/config.py +18 -11
  43. donna/{world → workspaces}/errors.py +55 -45
  44. donna/workspaces/initialization.py +78 -0
  45. donna/{world → workspaces}/markdown.py +21 -26
  46. donna/{world → workspaces}/sources/base.py +2 -2
  47. donna/{world → workspaces}/sources/markdown.py +8 -7
  48. donna/{world → workspaces}/templates.py +4 -4
  49. donna/workspaces/tmp.py +51 -0
  50. donna/{world → workspaces}/worlds/base.py +6 -3
  51. donna/{world → workspaces}/worlds/filesystem.py +30 -10
  52. donna/{world → workspaces}/worlds/python.py +12 -9
  53. donna-0.2.2.dist-info/METADATA +463 -0
  54. donna-0.2.2.dist-info/RECORD +92 -0
  55. {donna-0.2.0.dist-info → donna-0.2.2.dist-info}/WHEEL +1 -1
  56. donna/artifacts/work/do_it.md +0 -142
  57. donna/artifacts/work/do_it_fast.md +0 -98
  58. donna/artifacts/work/planning.md +0 -245
  59. donna/cli/commands/projects.py +0 -49
  60. donna/world/artifacts.py +0 -122
  61. donna/world/initialization.py +0 -42
  62. donna/world/tmp.py +0 -33
  63. donna/world/worlds/__init__.py +0 -0
  64. donna-0.2.0.dist-info/METADATA +0 -44
  65. donna-0.2.0.dist-info/RECORD +0 -85
  66. /donna/{artifacts/work → workspaces}/__init__.py +0 -0
  67. /donna/{world → workspaces}/sources/__init__.py +0 -0
  68. /donna/{world → workspaces/worlds}/__init__.py +0 -0
  69. {donna-0.2.0.dist-info → donna-0.2.2.dist-info}/entry_points.txt +0 -0
  70. {donna-0.2.0.dist-info → donna-0.2.2.dist-info}/licenses/LICENSE +0 -0
@@ -0,0 +1,463 @@
1
+ Metadata-Version: 2.4
2
+ Name: donna
3
+ Version: 0.2.2
4
+ Summary: A deterministic workflow and state orchestration engine for LLM agents.
5
+ License-Expression: BSD-3-Clause
6
+ License-File: LICENSE
7
+ Keywords: ai,agent,cli,llm,workflow
8
+ Author: Aliaksei Yaletski
9
+ Author-email: a.eletsky@gmail.com
10
+ Requires-Python: >=3.12,<4.0
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: BSD License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3 :: Only
18
+ Classifier: Topic :: Software Development :: Build Tools
19
+ Classifier: Topic :: Utilities
20
+ Requires-Dist: jinja2 (>=3.1,<3.2)
21
+ Requires-Dist: markdown-it-py (>=4.0,<4.1)
22
+ Requires-Dist: mdformat (>=1.0.0,<1.1.0)
23
+ Requires-Dist: pydantic (>=2.12,<2.13)
24
+ Requires-Dist: tomli-w (>=1.2,<1.3)
25
+ Requires-Dist: typer (>=0.20,<0.21)
26
+ Project-URL: Changelog, https://github.com/Tiendil/donna/blob/main/CHANGELOG.md
27
+ Project-URL: Homepage, https://github.com/Tiendil/donna
28
+ Project-URL: Issues, https://github.com/Tiendil/donna/issues
29
+ Project-URL: Repository, https://github.com/Tiendil/donna
30
+ Description-Content-Type: text/markdown
31
+
32
+ # FSM Driven Development
33
+
34
+ Your agent will generate [state machines](https://en.wikipedia.org/wiki/Finite-state_machine) while executing state machines that are generated by state machines.
35
+
36
+ ## What is Donna?
37
+
38
+ Donna is a CLI tool that helps coding agents like Codex focus on the task at hand by keeping high-level control flow in explicit Donna workflows. Donna dictates what should be done at each step of the work, so the agent can focus on the actual piece.
39
+
40
+ However, Donna is not an orchestrator; it is a tool for an agent — it can be used with any agent and does not require API keys or other credentials. You may look at Donna as the work diary or personal secretary for your agent.
41
+
42
+ The core idea:
43
+
44
+ - **Most high-level work is more algorithmic than it may seem at first glance.**
45
+ - **Most low-level work is less algorithmic than it may seem at first glance.**
46
+
47
+ For example, it may be non-trivial to fix a particular unit test, but the overall process of polishing the codebase is quite linear:
48
+
49
+ 1. Ensure all tests pass.
50
+ 2. Ensure the code is formatted correctly.
51
+ 3. Ensure there are no linting errors.
52
+ 4. Go to step 1 if you changed something in the process.
53
+ 5. Finish.
54
+
55
+ Coding agents show great results at each step of the process; however, they often struggle to manage meta-loops — they forget steps, misinterpret results, use the wrong approaches to run tools, etc.
56
+
57
+ Donna executes such loops for the agents, thereby saving time, context, and tokens and simultaneously increasing the overall quality of work.
58
+
59
+ ## Features
60
+
61
+ - **Deterministic workflows** — define fixed & validated control flow for agents to follow.
62
+ - **Saves context, tokens and time** — agents do not need to think when thinking is not required.
63
+ - **Readable artifacts** — all workflows and specifications are pure Markdown files with some [Jinja2](https://github.com/pallets/jinja) templating.
64
+ - **Artifact management** — non-fuzzy navigation and smart agent-focused rendering of artifacts.
65
+ - **Artifact distribution** — install your docs/workflows/skills as a Python lib.
66
+ - **Agent-centric behavior** — Donna guides agents through workflows, helps them be on the path, and fixes mistakes.
67
+ - **Extensible architecture** — implement your own operations, validators, renderers; add support for new artifact formats and storages (worlds).
68
+ - **Batteries included** — Donna goes with a set of pre-defined workflows, so you can start using it right away.
69
+
70
+ ## Example
71
+
72
+ Donna is developed via Donna itself. You can find real-life examples of workflows and specifications in the [.donna/project](./.donna/project) folder of this repository.
73
+
74
+ The example below is a simplified version of the polishing workflow that formats code, runs linters, and fixes found problems until all checks pass. It uses the single operation type `donna.lib.request_action` to ask the agent to perform specific instructions.
75
+
76
+ ```
77
+ no issues
78
+ [ run_black ] ──▶ [ run_mypy ] ───────────▶ [ finish ]
79
+ ▲ │
80
+ │ issues fixed │
81
+ └────────────────┘
82
+ ```
83
+
84
+ <details>
85
+ <summary><strong>An example source and comments</strong></summary>
86
+
87
+ ~~~
88
+ # Polishing Workflow
89
+
90
+ ```toml donna
91
+ kind = "donna.lib.workflow"
92
+ start_operation_id = "run_black"
93
+ ```
94
+
95
+ Polish and refine the codebase.
96
+
97
+ ## Run Black
98
+
99
+ ```toml donna
100
+ id = "run_black"
101
+ kind = "donna.lib.request_action"
102
+ ```
103
+
104
+ 1. Run `black .` to format the codebase.
105
+ 2. `{{ goto("run_mypy") }}`
106
+
107
+ ## Run Mypy
108
+
109
+ ```toml donna
110
+ id = "run_mypy"
111
+ kind = "donna.lib.request_action"
112
+ ```
113
+
114
+ 1. Run `mypy .` to check the codebase for type annotation issues.
115
+ 2. If there are issues found that you can fix, fix them.
116
+ 3. Ask the developer to fix any remaining issues manually.
117
+ 4. If you made changes `{{ goto("run_black") }}`.
118
+ 5. If no issues are found `{{ goto("finish") }}`.
119
+
120
+ ## Finish
121
+
122
+ ```toml donna
123
+ id = "finish"
124
+ kind = "donna.lib.finish"
125
+ ```
126
+
127
+ Polishing is complete.
128
+ ~~~
129
+
130
+ What you may notice:
131
+
132
+ 1. The workflow has a loop.
133
+ 2. The workflow is a Markdown file.
134
+ 3. Each h1 and h2 section has a config block, which is a TOML in code fences with `donna` marker. Those configs are invisible to the agent, but Donna uses them to understand the artifact structure.
135
+ 4. The workflow has two `donna.lib.request_action` operations (`run_black`, `run_mypy`) and one `donna.lib.finish` (`finish`).
136
+ 5. Transitions between operations are defined via `{{ goto("operation_id") }}` Jinja2 calls in the body of operations.
137
+ 6. `donna.lib.request_action` is an operation that tells Donna to display instructions to the agent and wait for the agent to complete them. That allows the agent to focus on short, precise instructions, perform them, and push workflow forward.
138
+ 7. `kind` attributes of sections are valid Python import paths, so you can easily extend Donna with your own code.
139
+
140
+ Directives, like `{{ goto("operation_id") }}`, render itself depending on the context:
141
+
142
+ - For the agent, they render an exact CLI command to run, such as `donna -p llm sessions action-request-completed <action-request-id> 'artifact_id:operation_id'`.
143
+ - For Donna, they render a specific marker that can be extracted and used to analyze an artifact. For example, Donna uses `goto` directives to build an FSM of the workflow and validate it before running: does each operation exist, can the workflow be completed, are there unreachable operations, etc.
144
+
145
+ Generally speaking, **all you need is `donna.lib.request_action` operation** — it is enough to achieve a great deal of automation by delegating some decisions to the agent. However, there are some more specific operations that simplify things and make workflows more agile or performant.
146
+
147
+ </details>
148
+
149
+ You can find a more complex implementation of the same workflow in the [polish.md](./.donna/project/work/polish.md) file. It demonstrates other Donna operations, such as running scripts directly and branching.
150
+
151
+ ## Installation
152
+
153
+ 1. Install `donna` package.
154
+
155
+ ```bash
156
+ pip install donna
157
+ ```
158
+
159
+ 2. Initialize Donna in your project.
160
+
161
+ ```bash
162
+ cd <your-project-root>
163
+ donna -p human workspaces init
164
+ ```
165
+
166
+ Donna will create a `.donna/` folder in your project root with a default configuration in `.donna/config.toml`.
167
+
168
+ 3. Add a short instruction into your `AGENT.md` file.
169
+
170
+ ```markdown
171
+ **Use `donna` tool to work on this project.**
172
+
173
+ **ALWAYS** run `donna -p llm artifacts view '*:intro'` when you start working on the project.
174
+ It **MUST** be a one time operation. Do not repeat it unless you forget how to use the tool.
175
+ ```
176
+
177
+ 4. Ask your agent to do something like `Add a button that …`. The agent will discover the appropriate workflow and run it.
178
+
179
+ ## Usage
180
+
181
+ **Donna is a CLI tool for agents.** You rarely need to use it directly.
182
+
183
+ Commands you may need:
184
+
185
+ - `donna -p human workspaces init` — Initialize Donna in your project.
186
+ - `donna -p human sessions start` — start a new working session, remove everything from the previous session.
187
+ - `donna -p human artifacts list <pattern>` — list artifacts with short descriptions.
188
+
189
+ Use `donna --help` for a quick reference.
190
+
191
+ You find detailed documentation in the agent instructions — they are readable and always accurate:
192
+
193
+ - [CLI specification](./donna/artifacts/usage/cli.md) — full list of commands and how to use them.
194
+ - [Artifacts](./donna/artifacts/usage/artifacts.md) — what are Donna artifact and how to use them.
195
+ - [Worlds](./donna/artifacts/usage/worlds.md) — how Donna discovers and manages its artifacts.
196
+
197
+ The documentation below covers aspects important to humans and partially duplicates the agent's instructions.
198
+
199
+ ## Batteries Included
200
+
201
+ Donna comes with built-in workflows and specifications that empower agents to work in a smart way.
202
+
203
+ However, **I encourage you to experiment and implement your own workflows**. Meta-programming is fun; specialized workflows are more efficient.
204
+
205
+ By default, Donna uses the next approach to introduce changes in your project:
206
+
207
+ 1. Prepare a Request for Change (RFC) document that describes the required changes.
208
+ 2. Create a workflow that implements the changes described in the RFC.
209
+ 3. Execute new workflow.
210
+
211
+ Additionally, Donna will:
212
+
213
+ - choose fast or slow route depending on the complexity of the changes required;
214
+ - find and run (if any) polishing workflow to ensure the codebase is in a good state after the changes;
215
+ - find and run (if any) workflow to update your changelog.
216
+
217
+ Points of interest:
218
+
219
+ - [donna:rfc:specs:request_for_change](./donna/artifacts/rfc/specs/request_for_change.md) — specification of the RFC document.
220
+ - [donna:rfc:work:create](./donna/artifacts/rfc/work/create.md) — workflow to create a RFC document.
221
+ - [donna:rfc:work:plan](./donna/artifacts/rfc/work/plan.md) — workflow to plan work on an RFC — creates a new workflow.
222
+ - [donna:rfc:work:do](./donna/artifacts/rfc/work/do.md) — meta workflow to automate the whole work from a developer request to a changelog update.
223
+
224
+ ## Artifacts and Worlds
225
+
226
+ - Artifacts are something that Donna owns. Currently, they are Markdown files with workflows and specifications.
227
+ - Worlds are storages for artifacts. Currently, Donna supports two types of worlds:
228
+ - `donna.lib.worlds.filesystem` — a folder on the filesystem.
229
+ - `donna.lib.worlds.python` — a Python package.
230
+
231
+ **Please, tell if you need other world types.** It looks interesting to have `http`, `s3`, `git`, `sql` worlds. How about an `email` world that allows you to send a workflow to someone agent and get the results back in your mailbox?
232
+
233
+ A world ID is the first part of an artifact ID. For example, `donna:usage:cli` artifact resides in the `donna` world.
234
+
235
+ By default, Donna uses the next worlds:
236
+
237
+ - `donna` — artifacts provided by Donna itself;
238
+ - `home` — user-level artifacts in `<HOME>/.donna/` folder;
239
+ - `project` — project-level artifacts in `<project-root>/.donna/project/` folder;
240
+ - `session` — session-level artifacts in `<project-root>/.donna/session/` folder.
241
+
242
+ Besides that, there is `<project-root>/.donna/tmp` folder used to store temporary files.
243
+
244
+ A world can be read-only. By default, writable worlds are `session` (current work scope) and `project` (project scope).
245
+
246
+ Agents are not allowed to edit artifacts directly because artifact consistency is important. Instead, they follow the next algorithm:
247
+
248
+ - Fetch an artifact into the temporary file with the command `donna -p llm artifacts fetch ...`.
249
+ - Edit the temporary file.
250
+ - Upload an artifact with the command `donna -p llm artifacts upload ...`.
251
+
252
+ On upload, Donna validates the artifact and accepts it only when there are no errors. For example, Donna will not accept a workflow that can not be finished.
253
+
254
+ ### Rendering
255
+
256
+ Markdown artifacts are Jinja2 templates. Donna uses multiple rendering modes for different purposes.
257
+
258
+ More about Jinja2 rendering is described a bit further.
259
+
260
+ ### Artifacts Discovery
261
+
262
+ Artifact is identified by its id: `<world>:<colon-separated-path>`, for example, `donna:usage:cli`.
263
+
264
+ You and agents can `list` artifacts and `view` them.
265
+
266
+ - `donna -p llm artifacts list <pattern>` — shows a short description from its h1 section.
267
+ - `donna -p llm artifacts view <pattern>` — shows the full content of the artifact with proper rendering.
268
+
269
+ Both commands accept both precise artifact ids and glob patterns. Patterns allow using:
270
+
271
+ - `*` to replace a single path segment;
272
+ - `**` to replace multiple path segments.
273
+
274
+ Examples:
275
+
276
+ - `*:artifact:name` — matches all artifacts named `artifact:name` in all worlds.
277
+ - `world:*:name` — matches all artifacts with id `something:name` in the `world` world.
278
+ - `**:name` — matches all artifacts with id ending with `:name` in all worlds.
279
+ - `world:**` — matches all artifacts in the `world` world.
280
+ - `world:**:name` — matches all artifacts with id ending with `:name` in the `world` world.
281
+
282
+ Both commands also accept `--tag <tag>` option to filter artifacts by their tags.
283
+
284
+ Currently, Donna supports two artifact tags:
285
+
286
+ - `workflow` — marks a workflow artifact — is set automatically by Donna.
287
+ - `specification` — marks a specification artifact — is set automatically by Donna.
288
+
289
+ You can find all workflows with the command `donna -p llm artifacts list '**' --tag workflow`.
290
+
291
+ ## Sessions
292
+
293
+ `session` world contains the current state of work performed by Donna: all documents and workflows that are created during work and should not be stored permanently in the project.
294
+
295
+ The developer is responsible for starting/resetting sessions with commands from `donna -p human sessions` group.
296
+
297
+ - On session start, Donna removes everything from the previous session and creates a fresh `session` world.
298
+ - On session reset donna resets the state of the current session (tasks, action requests, etc.), but keeps artifacts.
299
+
300
+ The agent is encouraged not to manage sessions directly, because it doesn't have enough context to decide when session artifacts may be safely removed.
301
+
302
+ ## Workflows
303
+
304
+ Workflows are [state machines](https://en.wikipedia.org/wiki/Finite-state_machine). They are defined in Markdown files with an h1 section of type `donna.lib.workflow` and multiple h2 sections that implement operations.
305
+
306
+ Donna tracks dependencies between operations and validates the workflow before running it. So, if you or your agent do something wrong, you'll get a clear error message from Donna.
307
+
308
+ You can run workflow as `donna -p llm sessions run <artifact-id>`.
309
+
310
+ To execute a workflow, Donna uses a simplified virtual machine (VM) that maintains the current state of all workflows executed in the current session.
311
+
312
+ <details>
313
+ <summary><strong>What you may want to know about workflows implementation</strong></summary>
314
+ - `.donna/session/state.json` file contains the current state of all running workflows in the current session.
315
+ - Each workflow executes in the context of its own task, which is a distant analog of a call stack frame. So, we may look at workflows as functions.
316
+ - Of course, workflows may call other workflows as subroutines. At any moment, only last executed workflow is active.
317
+ - Task has a context that is accessible by operations. There is an issue [command to read/write task context](https://github.com/Tiendil/donna/issues/47) to allow agents and humans to edit task context.
318
+ - The internal VM operates in terms of work units. An operation can produce multiple work units, so it should be possible to implement different interesting scenarios; however.
319
+ </details>
320
+
321
+ ### Operations
322
+
323
+ You can find detailed docs on built-in operations in the [artifacts documentation](./donna/artifacts/usage/artifacts.md).
324
+
325
+ Here is a short list of them:
326
+
327
+ - `donna.lib.request_action` — request the agent to perform specific instructions.
328
+ - `donna.lib.run_script` — run a script from the environment Donna is running in. Choose the next operation based on the return code. Can store `stdout` and `stderr` in the task context.
329
+ - `donna.lib.output` — output a cell with specific content and immediately goes to the next operation.
330
+ - `donna.lib.finish` — finish the workflow. This operation MUST be present in the workflow and MUST end all possible execution paths.
331
+
332
+ ### Error handling
333
+
334
+ Donna can detect errors (in artifacts, in execution, etc). If an error can be fixed by the agent or the developer, Donna will output a detailed error description with a list of ways to fix it.
335
+
336
+ <details>
337
+ <summary><strong>An example of error message from Donna</strong></summary>
338
+
339
+ ```bash
340
+ $ donna -p llm sessions run project:work:polish
341
+
342
+ kind=artifact_validation_error
343
+ media_type=text/markdown
344
+ artifact_id=project:work:polish
345
+ error_code=donna.artifacts.section_not_found
346
+ section_id=run_autoflake_scriptx
347
+
348
+ Error in artifact 'project:work:polish', section 'run_autoflake_scriptx': Section `run_autoflake_scriptx` is not available in artifact `project:work:polish`.
349
+
350
+ Ways to fix:
351
+
352
+ - Check the section id for typos.
353
+ - Ensure the section exists in the artifact
354
+ ```
355
+
356
+ </details>
357
+
358
+ ### Generating workflows
359
+
360
+ The power of Donna comes from the ability to create workflows on the fly and execute them immediately. So, you can create a workflow that creates a workflow that creates a workflow that does something useful :)
361
+
362
+ You can even modify the workflow while it is executing; the only requirement is not to lose the ids of the operations referenced in action requests.
363
+
364
+ The simplest example of such generation is currently used as a primary way for Donna to work on the current project:
365
+
366
+ 1. Create a document with a change description.
367
+ 2. Generate a workflow that defines an order of applying changes.
368
+ 3. Execute the generated workflow.
369
+
370
+ ### Discovering workflows
371
+
372
+ If you want to run a child workflow from an operation, you can just instruct an agent like `Run the workflow project:work:my-cool-workflow` and the agent will find it and run.
373
+
374
+ However, it is not very agile. Instead, I suggest you describe the desired outcome and let the agent find the most suitable workflow. In that case, you'll be able to define customized workflows for specific types of changes and let the agent choose the best one for the current situation.
375
+
376
+ For example, you can have two workflows `project:work:write-backend-test` and `project:work:write-frontend-test`, and your operation can say `Run the workflow that will write a test for the current change`, and the agent will choose the most suitable workflow based on the context and the workflow descriptions.
377
+
378
+ ## Jinja2 rendering
379
+
380
+ Markdown artifacts are Jinja2 templates that are rendered immediately upon loading, before parsing Markdown.
381
+
382
+ There are multiple rendering modes that Donna uses for different purposes:
383
+
384
+ 1. `view` — artifact is rendered for displaying to the agent or the developer.
385
+ 2. `execute` — artifact is rendered for execution. This mode has access to the current task context, so we can add a variable from it into the operation instructions.
386
+ 3. `analyze` — artifact is rendered to be analyzed by Donna itself. For example, to extract `goto` directives from operation bodies and validate the workflow structure.
387
+
388
+ All Jinja2 rendering is supported, except inheritance-related features. So, an artifact is self contained template.
389
+
390
+ The rendering is performed before processing Markdown, so you can use Jinja2 features (like loops, conditionals, etc) to generate complex artifacts.
391
+
392
+ ### Directives
393
+
394
+ Donna defines a set of built-in Jinja2 functions that provide artifacts with their special capabilities. Such functions are called directives.
395
+
396
+ Directives are used in the next way: `{{ python.import.path(<args>) }}`.
397
+
398
+ You can find a detailed documentation of all built-in directives in the [artifacts documentation](./donna/artifacts/usage/artifacts.md).
399
+
400
+ Here they are:
401
+
402
+ 1. `donna.lib.view` — references another artifact. In `view`/`execute` modes, it renders an exact CLI command to view the artifact. In analysis mode, it will be used to validate the existence of the artifact and track dependencies between artifacts.
403
+ 2. `donna.lib.list` — references artifact listing. In `view`/`execute` modes, it renders an exact CLI command to list artifacts. In analysis mode, it will be used to validate the existence of the artifacts and track dependencies between artifacts.
404
+ 3. `donna.lib.goto` — references the next workflow operation to execute. In `view`/`execute` modes, it renders an exact CLI command to advance the workflow. In `analysis` mode, it is used to construct and validate an FSM for the workflow.
405
+ 4. `donna.lib.task_variable` — in `view` mode renders a placeholder with a note about task-variable substitution, in `execute` mode renders the actual task-context value. In `analysis`, it will be used to control a set of variables used in the artifact.
406
+
407
+ ## Specifications
408
+
409
+ Specifications can be perceived just as documentation. There is no special handling for them.
410
+
411
+ Later, they will be validated like workflows, but currently, it is just docs.
412
+
413
+ ## Extending Donna
414
+
415
+ All Donna logic is referenced by Python import paths. That means:
416
+
417
+ - You can implement your own functionality and use it with Donna.
418
+ - You can enrich your Python packages with additional code to work with Donna.
419
+ - You can distribute your Donna artifacts as Python packages.
420
+
421
+ What you can implement:
422
+
423
+ - Custom sections (including operations) for Donna artifacts. Check [./donna/primitives/artifacts](./donna/primitives/artifacts) and [./donna/primitives/operations](./donna/primitives/operations) subpackages for examples.
424
+ - Custom rendering directives. Check [./donna/primitives/directives](./donna/primitives/directives) subpackage for examples.
425
+ - Custom worlds. Check [./donna/workspaces/worlds](./donna/workspaces/worlds) subpackage for examples.
426
+ - Custom parsers for artifacts. Check [./donna/workspaces/sources](./donna/workspaces/sources) subpackage for examples.
427
+
428
+ Worlds and sources are configured in the `.donna/config.toml` file of your project.
429
+
430
+ Sections and directives are used directly in artifacts by their Python import paths.
431
+
432
+ ## Distribute Your Artifacts
433
+
434
+ Since Donna world can be a Python lib, you can distribute your artifacts as a Python package.
435
+
436
+ To define a Donna world in you package you must place a variable `donna_artifacts_root` in your package `__init__.py` file with a import path to the root subpackage with your artifacts.
437
+
438
+ On the example of Donna:
439
+
440
+ ```python
441
+ donna_artifacts_root = "donna.artifacts"
442
+ ```
443
+
444
+ After that, you can install your package and add the world into the `.donna/config.toml` file of your project.
445
+
446
+ Since you distribute text files, **you package is not dependent on Donna itself — no additional dependencies are required.**
447
+
448
+ ## Feedback wanted
449
+
450
+ Donna is still young and has multiple experimental features — I really appreciate any feedback, ideas, and contributions to make it better.
451
+
452
+ Especially, it would be nice to hear about
453
+
454
+ - problems with configuration and usage;
455
+ - real-life use cases, especially with meta programming: fun workflows that generate workflows and so on;
456
+ - your particular needs that Donna potentially can cover, but lacks some functionality now.
457
+
458
+ How to reach me:
459
+
460
+ - Create an [issue](https://github.com/Tiendil/donna/issues). Any format and theme is welcome.
461
+ - Comment on one of the existing issues. Feedback, especially on [proposals](https://github.com/Tiendil/donna/issues?q=is%3Aissue%20state%3Aopen%20label%3Aproposal).
462
+ - Start a [discussion](https://github.com/Tiendil/donna/discussions).
463
+
@@ -0,0 +1,92 @@
1
+ donna/__init__.py,sha256=lEC7l3wDCBiC5gw56XkAeBW1XJA52pck7SFR1_CUals,41
2
+ donna/artifacts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
3
+ donna/artifacts/intro.md,sha256=FnZOmoTSIO8GiGCkJFYLyXgyh9RafhTiyA4qDJ11ivg,2141
4
+ donna/artifacts/research/specs/report.md,sha256=r3D5Jb5hJNsGyh4hM2ewiKIopb7yHFD6f6MBxxwLG_Q,8598
5
+ donna/artifacts/research/work/research.md,sha256=Zyp4quC-7Dg7H1UeDixzo9z2Myj87FFlcpSMA4l8sl8,7081
6
+ donna/artifacts/rfc/specs/request_for_change.md,sha256=tEaowYtT-sRtPQ-LT1DJn5florLoZIHCt1_wUzJhQVE,13008
7
+ donna/artifacts/rfc/work/create.md,sha256=mTsxlLnHk3X7TAS60TOsB9wlXd7M3EWhO9XD3FnguHk,3772
8
+ donna/artifacts/rfc/work/do.md,sha256=GOqjcozVv7Oubg9Zg79zD8fCqQMiEyla5EEQECSkNLU,2952
9
+ donna/artifacts/rfc/work/plan.md,sha256=xqWLf-7eRGdzVtaAFxdtlts3sZcdhtu_Q1nTYewwy5Q,2574
10
+ donna/artifacts/usage/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
11
+ donna/artifacts/usage/artifacts.md,sha256=BHo7yW2rd_TLTyvCGpnEBk86XkWHp1nt7uZvRlBVODc,13638
12
+ donna/artifacts/usage/cli.md,sha256=u1uy2oUhqAtnBJLKxgW8wBZGvz7iVvyeIYf7lmuUHZY,10781
13
+ donna/artifacts/usage/worlds.md,sha256=iA61-ZzS29NLxrdVQhdSF-2hpS6wGO1stlWkMkHnNDU,2078
14
+ donna/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
15
+ donna/cli/__main__.py,sha256=_zo9JRR0m_ggVlrSaCpwo84bo0-cR9DgnJFup1AcH5U,224
16
+ donna/cli/application.py,sha256=rIEseTvPZgX4tZ23fTX49LF0XLfyzTO8gtpA8G80MTI,466
17
+ donna/cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
18
+ donna/cli/commands/artifacts.py,sha256=qakcdQ_9h4ZE1Yw0xxNfA5vhxWEPRsZjA0DjJdsNvp0,6416
19
+ donna/cli/commands/sessions.py,sha256=UNWLkt_s_u06yvw30hjb__TRzhcPpyCKue6i6YjY39c,2142
20
+ donna/cli/commands/workspaces.py,sha256=ZFTFCojhi14njRFsCIpXjUWYY_aYyLH06xLFNTRDrk4,1078
21
+ donna/cli/errors.py,sha256=9UzGo4tINr3EEwhOu361M7ulGS-bEe7wGgVivu07Z1o,524
22
+ donna/cli/types.py,sha256=ZWALGkmfZQ62C8Sb6nGRkSLi0g79cEM0cAUQoITn1v0,3692
23
+ donna/cli/utils.py,sha256=rtgtCttr-txPVp1BNJYF9Nfb8zMAnBFsZ7ORsYaLsRw,1418
24
+ donna/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
25
+ donna/core/entities.py,sha256=Y3udcI1ykWDI_yPqCX6JTuDmF81BxO0PnnJzzD5uMoM,753
26
+ donna/core/errors.py,sha256=jkblzdC1bk0-E5eSGiiPSSIEHPbUbz88CXPvrHdLVuU,3313
27
+ donna/core/result.py,sha256=3QLzoRWs9ph_oGcWYbephbZjx97M_0Ayx_yFhweOcFo,2374
28
+ donna/core/utils.py,sha256=lviOkI-aFGWMy-3_VWVdf7iKGdOsIZtEzEa-5f618mk,1141
29
+ donna/domain/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
30
+ donna/domain/errors.py,sha256=jewM3wYUCGLwNb8tvHkJ35-Y59ezJKgWy7pr_Utk7iA,1253
31
+ donna/domain/ids.py,sha256=CMEBRj6i2vjVi74TtUcjLTALn3MqKsEbs-Iv463mjVg,14678
32
+ donna/lib/__init__.py,sha256=01wddMlBwKz3gtcWiSD1rAKfhMMtsp_n90DHCplWRzI,987
33
+ donna/lib/sources.py,sha256=VvnAsIm7V_CnQeEN7KqB5Z-5yzQOmz3TTAYpB6MxZZk,182
34
+ donna/lib/worlds.py,sha256=w6QmpSx3gF0q71GyTdWQAKgMwT5VaMHAa_0FdNiyOnI,286
35
+ donna/machine/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
36
+ donna/machine/action_requests.py,sha256=BRJHHex3O0-3MT2hf66QdkaSrjCA84wKBXscr1zwVtk,1249
37
+ donna/machine/artifacts.py,sha256=IpwVDUV3lUEuA80hHDSoRd3qcjYoDbZpPF7EO4VFi-o,6627
38
+ donna/machine/changes.py,sha256=TlgMA70u0ffRvwKVBwXEgEk1bp4m9w9MsVxtishX9Sw,2463
39
+ donna/machine/errors.py,sha256=45EPNC12rRT2pdgd2b9HMXCP0aon4sxo9DdUfxXeMnQ,4956
40
+ donna/machine/operations.py,sha256=CHXPy8hDYNqE5woVMj_lu2p4wgl7fqRxO0Dz0v1t4zI,761
41
+ donna/machine/primitives.py,sha256=FYg4uS-UhMIV59Vqs-eKeHQdf00F4uu9KK0aIqNNJ8I,3287
42
+ donna/machine/sessions.py,sha256=lpvsdtscaifIsosUvl57zptAlPcZ8y708E6sZtZcCZA,7134
43
+ donna/machine/state.py,sha256=jvf8AQXf5rZbjZNOOcxRSR1XAoOPwk2jAuV4YPsFlFE,8117
44
+ donna/machine/tasks.py,sha256=2dfz5AoXC0pBH7t7x2SXSfZTM7_3tMYXRjJClGJY_Xc,2175
45
+ donna/machine/templates.py,sha256=oIlvYgpeuofq52sKtGvhlB850FQeuBIuwCkphoaOvss,2535
46
+ donna/primitives/__init__.py,sha256=CfJhz3TLdFxYbqCXioWVAIKGQ2tAMwXwL_Fg3A68Dqo,53
47
+ donna/primitives/artifacts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
48
+ donna/primitives/artifacts/specification.py,sha256=SYqRHJwfIvSVd0PTrrLG_Q0IdNy2mbdeK73Y1bt80_o,844
49
+ donna/primitives/artifacts/workflow.py,sha256=4u4Y9Le8ICKqWJR6qmC-flXKMers9Udm4vzKCHHLMME,7939
50
+ donna/primitives/directives/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
51
+ donna/primitives/directives/goto.py,sha256=uJdMJe3leJPSl_0PU4jd2AbHFJsJkf-x6rKhn4hKZd8,1679
52
+ donna/primitives/directives/list.py,sha256=VgpUdZyGFQJbuhbMxNqRBWGn0_75u9lEzgjjKTqFKZY,3198
53
+ donna/primitives/directives/task_variable.py,sha256=KvxY8ZOKFh6alkBhgDvkWzIJBfRNP4oYKRJ0SgHzO_g,2959
54
+ donna/primitives/directives/view.py,sha256=-FvVKksxTx8WyyZgsh2jkauqQOWf7b5LL201dbv_hac,3198
55
+ donna/primitives/operations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
56
+ donna/primitives/operations/finish_workflow.py,sha256=-3vaYAjj6oN93JWeQIoV9TOqzDjv-2ch_Wp4pXcOHvs,1846
57
+ donna/primitives/operations/output.py,sha256=P0eYKK7-dUMfalVqFySHVY57RylBhhG-t8_xcTEZ4xE,3316
58
+ donna/primitives/operations/request_action.py,sha256=aovOrEIfyzaiqiLEvR-dUNgCEaIEX2x1uHPEDUMQtq4,2893
59
+ donna/primitives/operations/run_script.py,sha256=R72TCPv-vsI9sZzkyikw6dulmW4iSIKWT4vEGYU4vjc,9348
60
+ donna/protocol/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
61
+ donna/protocol/cell_shortcuts.py,sha256=dZVCzoaPu09IYEA5g5gYPhR-q8MpgmehcYti1z9BBuI,385
62
+ donna/protocol/cells.py,sha256=jQCM-l31Kt7gEBXgvb7Ph5Fstbz9lf0lEUbH0bgNlWg,1348
63
+ donna/protocol/errors.py,sha256=u54fxMtJMWL8cbOLWU0acrmxV7Q8uHnyT1NFw959SMI,486
64
+ donna/protocol/formatters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
65
+ donna/protocol/formatters/automation.py,sha256=I_I-b8bixuXBlKqn2ryHDKSdRJy77FzDATJi-jhEPWI,928
66
+ donna/protocol/formatters/base.py,sha256=PGrAgxiEtZKyg1wPePQMt5syOr6IpC4ydh5rMElaojE,405
67
+ donna/protocol/formatters/human.py,sha256=WvoZVYlD4H3MftDkpEEP_RtyZnzJhUWKNecKgm3FoXg,1168
68
+ donna/protocol/formatters/llm.py,sha256=z_2djZFaVVHjLYFMneUrYp5sA-EvtPuHUDzGKV1ogu4,1266
69
+ donna/protocol/modes.py,sha256=vFDjciPdPy26XlLBGrgAn1kAVW7EJAHrccGcJrK7vUo,960
70
+ donna/protocol/nodes.py,sha256=aP5IVOouZe6akSdfzPpfcGuZLbxkEieTE6j6SuVuTUU,1974
71
+ donna/protocol/utils.py,sha256=GMiqGH2vawKu8_MmofWhCljI7AqoYDI0w19I-21t02g,663
72
+ donna/workspaces/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
73
+ donna/workspaces/artifacts.py,sha256=co6MBjIX2kV91WgNqCnDiK01hqUeB5cGPhE_ftJMl8U,8254
74
+ donna/workspaces/artifacts_discovery.py,sha256=JEf5ZVLaK2wwhx5mVE4ulOdmC2lApCdyfpfv2vBB_DE,2803
75
+ donna/workspaces/config.py,sha256=qe8gtSt95ZLyoDWgXSfEMn2AXfL9WkY7pVpmea8iot4,6454
76
+ donna/workspaces/errors.py,sha256=ZK77AKjnRLc0-Qnu-NKztliSbCYBDmzr71fo1soWDrg,8276
77
+ donna/workspaces/initialization.py,sha256=d2oRwU4YEhhDeB1UtcOhqT0LD08QJoWEtvmSoQ6QwMg,2456
78
+ donna/workspaces/markdown.py,sha256=Aom9AnnpGHXI8LndmizwwG5r6aIFlosHjCvw-juL85Q,7214
79
+ donna/workspaces/sources/__init__.py,sha256=IRwKWnqQKh1ase742jhdadBcS4E9Hxr6j_l9Li6wwfw,70
80
+ donna/workspaces/sources/base.py,sha256=y6CawcOSBUX3oMO8YXlxE6p_NMJ713ukTZhgNKKBl94,2020
81
+ donna/workspaces/sources/markdown.py,sha256=8xIYza-48xCmLMw2CCUw-d8yv3PWSyS0HooFmxiZMSU,9740
82
+ donna/workspaces/templates.py,sha256=tovUVXCHKfHDymr7jxPO_nN-7r_-K_pcmzkdBa9FEes,6092
83
+ donna/workspaces/tmp.py,sha256=PetBKOpQJD3fU4jODjaBk8MiFm5ADuJyRc03S5KgKV8,1330
84
+ donna/workspaces/worlds/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
85
+ donna/workspaces/worlds/base.py,sha256=mdmAT1WV5tYe-GnWlxeDXXzO1qT6Q4u0itpHZafc408,2590
86
+ donna/workspaces/worlds/filesystem.py,sha256=0zCQwM0RuPOJKm1EsODpgmL9NXk6z0fanJZMXfC79rI,7231
87
+ donna/workspaces/worlds/python.py,sha256=dRPS4jHIMRqdecCAmF7FuC6IwH3__nfWaf2cMSc7Txk,7223
88
+ donna-0.2.2.dist-info/METADATA,sha256=KMTxxXts2hCLPlyIq4gTg9pqy_F8_YBFX_cpsgKtUCg,23561
89
+ donna-0.2.2.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
90
+ donna-0.2.2.dist-info/entry_points.txt,sha256=r2W_yOzauooYCu312OQwCycIN1UjVnO5paPpS2EDZqo,48
91
+ donna-0.2.2.dist-info/licenses/LICENSE,sha256=KiF6_RVxH0MLeHZZtc8ag497X-c6oPmk-0OOf9qQDDk,1504
92
+ donna-0.2.2.dist-info/RECORD,,
@@ -1,4 +1,4 @@
1
1
  Wheel-Version: 1.0
2
- Generator: poetry-core 2.3.0
2
+ Generator: poetry-core 2.3.1
3
3
  Root-Is-Purelib: true
4
4
  Tag: py3-none-any