donna 0.2.0__tar.gz → 0.2.1__tar.gz

{donna-0.2.0 → donna-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: donna
-Version: 0.2.0
+Version: 0.2.1
 Summary: A deterministic workflow and state orchestration engine for LLM agents.
 License-Expression: BSD-3-Clause
 License-File: LICENSE
@@ -11,6 +11,7 @@ Requires-Python: >=3.12,<4.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -20,7 +21,9 @@ Requires-Dist: jinja2 (>=3.1,<3.2)
 Requires-Dist: markdown-it-py (>=4.0,<4.1)
 Requires-Dist: mdformat (>=1.0.0,<1.1.0)
 Requires-Dist: pydantic (>=2.12,<2.13)
+Requires-Dist: tomli-w (>=1.2,<1.3)
 Requires-Dist: typer (>=0.20,<0.21)
+Project-URL: Changelog, https://github.com/Tiendil/donna/blob/main/CHANGELOG.md
 Project-URL: Homepage, https://github.com/Tiendil/donna
 Project-URL: Issues, https://github.com/Tiendil/donna/issues
 Project-URL: Repository, https://github.com/Tiendil/donna

donna-0.2.1/donna/artifacts/intro.md

@@ -0,0 +1,39 @@
+# Intoduction to the Donna tool
+
+```toml donna
+kind = "donna.lib.specification"
+```
+This document provides an introduction to the Donna — a CLI tool that helps manage the work of AI agents like Codex.
+
+## Overview
+
+Donna is designed to to invert control flow: instead of agents deciding what to do next, the `donna` tells agents what to do next by following predefined workflows.
+
+The core idea is that most of high-level workflows are more algorithmic than it may seem at first glance. For example, it may be difficult to fix a particular type issue in the codebase, but the overall process of polishing the codebase is quite linear:
+
+1. Ensure all tests pass.
+2. Ensure the code is formatted correctly.
+3. Ensure there are no linting errors.
+4. Go to the step 1 if you changed something in the process.
+5. Finish.
+
+We may need coding agents on the each step of the process, but there no reason for agents to manage the whole grooming loop by themselves — it take longer time, spends tokens and may lead to confusion of agents.
+
+## Artifact Tags
+
+To simplicity searching of artifacts by their semantics, Donna allows tagging artifacts with semantically valuable keywords. Artifacts in `donna:*` world use the next set of tags.
+
+Artifact type tags:
+
+- `workflow` — workflow artifact — is set automatically by Donna.
+- `specification` — specification artifact — is set automatically by Donna.
+
+{# We recommend using those tags in `project:` and `session:` worlds as well to keep consistency. #}
+
+## Instructions
+
+1. On start of the YOUR session you **MUST** read and understand instruction on using the Donna tool `{{ donna.lib.view("donna:usage:cli") }}`. It **MUST** be a one time operation. Do not repeat it unless you forget how to use the tool.
+2. If you need to perform a work with Donna, you **MUST** select an appropriate Donna workflow to perform the work and run it.
+3. If there is no appropriate workflow, ask the developer for a precise instructions on what to do.
+4. List all workflows: `{{ donna.lib.list("**", tags=["workflow"]) }}`
+5. List all specifications: `{{ donna.lib.list("**", tags=["specification"]) }}`

donna-0.2.1/donna/artifacts/research/specs/report.md

@@ -0,0 +1,163 @@
+# Format of the Research Report document
+
+```toml donna
+kind = "donna.lib.specification"
+```
+
+This document describes the format and structure of a Research Report document used by Donna workflows from `donna:research:*` namespace.
+
+## Overview
+
+Donna introduces a group of workflows located in `donna:research:*` namespace that organize the process of researching a problem, collecting information, analyzing it, synthesizing options, and producing a final solution.
+
+Session-related research artifacts MUST be stored as `session:research:<short-problem-related-identifier>`, unless the developer or parent workflow specifies a different location. The `<short-problem-related-identifier>` MUST be unique within the session.
+
+Agent (via workflows) creates that artifact and updates it iteratively as the research process goes on.
+
+## Research report structure
+
+The research report is a Donna artifact (check `{{ donna.lib.view("donna:usage:artifacts") }}`) with the next structure:
+
+- **Primary section** -- title and short description of the research problem.
+- **Original problem description** -- original problem statement from the developer or parent workflow.
+- **Formalized problem description** -- formalized version of the problem statement.
+- **Goals** -- list of goals the research should achieve.
+- **Desired form of final solution** -- description of the expected form and constraints for the final solution.
+- **Solution space** -- description of analysis axes and synthesis dimensions.
+- **Information to collect** -- list of information required to research the problem.
+- **Information sources** -- list of sources that can provide the required information.
+- **Collected information** -- gathered information with source references.
+- **Analysis** -- analysis of collected information along the specified axes.
+- **Synthesized solutions** -- synthesized solution options along the specified dimensions.
+- **Evaluation** -- evaluation of synthesized solutions against the goals.
+- **Final solution** -- final solution in the desired form.
+
+## General language and format
+
+- You MUST follow [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119.txt) for keywords like MUST, SHOULD, MAY, etc.
+- You MUST follow `{{ donna.lib.view("donna:usage:artifacts") }}`.
+- You MUST follow the structure specified in this document.
+
+### List format
+
+- If a section described as a list, it MUST contain only a single markdown list.
+- Each list item MUST be concise and clear.
+- Each list item SHOULD be atomic and focused on a single aspect.
+- Reviewer MUST be able to tell if the list item statement is true or false by inspecting resulting artifacts and behavior.
+
+Common approaches to improve list items:
+
+- Split a single item with an enumeration into multiple items with single focus.
+- Transform an abstract item into a concrete one by referencing specific artifacts, measurable criteria, verifiable conditions, etc.
+
+### Trusted inputs
+
+Some sections of the research report MUST be based on trusted inputs. Trusted inputs are:
+
+- Original problem description from the developer or parent workflow.
+- Statements from the research report itself.
+- Existing project documentation, code, and artifacts.
+- External standards when they define constraints or best practices for the project domain.
+- Documentation of third-party libraries, frameworks, or tools when it describes constraints or best practices.
+- Primary research sources (datasets, reports, official publications) used to collect the required information.
+
+## `Primary` section
+
+- Title MUST be concise and reflect the essence of the research problem.
+- Description MUST provide a brief overview of the problem, its purpose, and why research is needed.
+
+## `Original problem description` section
+
+- This section MUST contain the original problem description from the developer or from the parent workflow.
+- The problem description MUST NOT be modified by agents.
+
+## `Formalized problem description` section
+
+- The section MUST contain a clear professional high-level description of the problem based on the original description.
+- The section MUST be limited to a single paragraph with a few sentences.
+- The section MUST explain what someone gains after the problem is solved and how they can see it working.
+
+## `Goals` section
+
+- This section MUST contain a list of goals that the research should achieve.
+- Each goal MUST be grounded in the formalized problem description.
+
+Goal quality criteria:
+
+- A goal MUST be a desired end state, outcome, or result.
+- A goal MUST define what ultimately should be true, not how to achieve it.
+
+Examples:
+
+- Bad: `- Investigate database options.`
+- Good: `- Identify a database option that meets the project's scalability requirements.`
+
+## `Desired form of final solution` section
+
+- The section MUST be grounded in the formalized problem description and the goals.
+- The section MUST describe the expected form of the final solution (for example: recommendation, decision matrix, implementation plan, or specification).
+- The section MUST specify any required structure, formatting, or constraints on the final solution.
+- The section SHOULD be a short list or a short paragraph, whichever is clearer for the problem.
+
+## `Solution space` section
+
+- The section MUST describe the axes along which collected information will be analyzed and the dimensions along which solutions will be synthesized.
+- The section MUST contain two subsections: **Analysis axes** and **Synthesis dimensions**.
+- Each axis or dimension MUST be grounded in the goals or the formalized problem description.
+
+### `Analysis axes` subsection
+
+- The subsection MUST contain a list of analysis axes.
+- Each axis MUST describe a single perspective or criterion used to analyze information.
+- Each axis SHOULD be phrased so it is clear how to apply it to collected information.
+
+### `Synthesis dimensions` subsection
+
+- The subsection MUST contain a list of synthesis dimensions.
+- Each dimension MUST describe a single perspective or criterion used to synthesize solution options.
+- Each dimension SHOULD make the comparison between options easier.
+
+## `Information to collect` section
+
+- The section MUST contain a list of information items required to research the problem.
+- Each item MUST be specific enough to be collected or verified from sources.
+- Each item MUST be grounded in the formalized problem description or the goals.
+
+## `Information sources` section
+
+- The section MUST contain a list of sources that can provide the required information.
+- Each source entry MUST include a short identifier and a brief description of the source.
+- Each source entry SHOULD include access method, scope, and reliability notes if relevant.
+- Each source MUST be relevant to at least one item from **Information to collect**.
+
+## `Collected information` section
+
+- The section MUST contain the collected information mapped to the items from **Information to collect**.
+- Each collected information item MUST reference one or more source identifiers from **Information sources**.
+- The section MUST make it clear which information items are satisfied and which are missing.
+- If a required information item cannot be collected, the section MUST state that explicitly and explain why.
+
+## `Analysis` section
+
+- The section MUST analyze the collected information along the **Analysis axes**.
+- The analysis MUST be organized so each axis can be reviewed independently.
+- The analysis MUST clearly separate observed facts from inferences or assumptions.
+- The analysis format MUST fit the **Desired form of final solution** and should make downstream synthesis straightforward.
+
+## `Synthesized solutions` section
+
+- The section MUST present synthesized solutions or options in a format consistent with the **Synthesis dimensions**.
+- Each solution SHOULD reference the analysis items that justify it.
+- The synthesis format MUST fit the **Desired form of final solution**.
+
+## `Evaluation` section
+
+- The section MUST evaluate each synthesized solution against the **Goals**.
+- The evaluation MUST make trade-offs explicit and identify risks or uncertainties.
+- The evaluation MUST result in a clear comparison between solutions.
+
+## `Final solution` section
+
+- The section MUST present the final solution in the form specified in **Desired form of final solution**.
+- The final solution MUST be justified by the evaluation results.
+- If the evaluation does not allow a confident final solution, the section MUST state the remaining uncertainties and what additional information would resolve them.

donna-0.2.1/donna/artifacts/research/work/research.md

@@ -0,0 +1,198 @@
+# Research workflow
+
+```toml donna
+kind = "donna.lib.workflow"
+start_operation_id = "start"
+```
+
+Workflow for performing research on a given question/problem/situation. Collects relevant information, analyzes it, synthesizes possible options, and produces an answer/solution/deliverables.
+
+The purpose of this workflow is to provide an information for making decisions or producing solutions based on researched data. It can be used:
+
+- When the developer explicitly asks to make a research.
+- When other workflows need to perform research as a subtask.
+
+## Start
+
+```toml donna
+id = "start"
+kind = "donna.lib.request_action"
+fsm_mode = "start"
+```
+
+1. Read the specification `{{ donna.lib.view("donna:usage:artifacts") }}` if you haven't done it yet.
+2. Read the specification `{{ donna.lib.view("donna:research:specs:report") }}` if you haven't done it yet.
+3. `{{ donna.lib.goto("ensure_problem_description_exists") }}`
+
+## Ensure problem description exists
+
+```toml donna
+id = "ensure_problem_description_exists"
+kind = "donna.lib.request_action"
+```
+
+At this point you SHOULD have a clear description of the problem in your context. I.e. you know what you need to do in this workflow.
+
+1. If you have a problem description in your context, `{{ donna.lib.goto("prepare_artifact") }}`.
+2. If you have no problem description in your context, but you know it is in one of `session:*` artifacts, find and view it. Then `{{ donna.lib.goto("prepare_artifact") }}`.
+3. If you have no problem description in your context, and you don't know where it is, ask the developer to provide it. After you get the problem description, `{{ donna.lib.goto("prepare_artifact") }}`.
+
+## Prepare research artifact
+
+```toml donna
+id = "prepare_artifact"
+kind = "donna.lib.request_action"
+```
+
+1. Based on the problem description you have, suggest an artifact name in the format `session:research:<short-problem-related-identifier>`. `<short-problem-related-identifier>` MUST be unique within the session.
+{# TODO: we can add donna.lib.list('session:*') here as the command to list all artifacts in session #}
+2. Create the artifact and specify an original problem description in it.
+3. `{{ donna.lib.goto("formalize_research") }}`
+
+## Formalize Research
+
+```toml donna
+id = "formalize_research"
+kind = "donna.lib.request_action"
+```
+
+1. Using your knowledge about the project and the original problem description, formulate a format description of the problem
+2. Update the artifact with the formalized problem description.
+3. `{{ donna.lib.goto("set_primary_section_of_the_research_artifact") }}`
+
+## Set primary section of the research artifact
+
+```toml donna
+id = "set_primary_section_of_the_research_artifact"
+kind = "donna.lib.request_action"
+```
+
+1. Based on the formalized problem description, update the primary (h1) section of the research artifact to reflect the problem being researched. So the agents can effectively find and understand the research artifact using Donna.
+2. `{{ donna.lib.goto("formulate_goals") }}`
+
+## Formulate Goals
+
+```toml donna
+id = "formulate_goals"
+kind = "donna.lib.request_action"
+```
+
+1. Based on the formalized problem description, formulate a list of goals that the problem solution should achieve.
+2. Update the artifact with the list of goals.
+3. `{{ donna.lib.goto("fomalize_form_of_final_solution") }}`
+
+## Formalize form of final solution
+
+```toml donna
+id = "fomalize_form_of_final_solution"
+kind = "donna.lib.request_action"
+```
+
+1. Based on the formalized problem description and the list of goals, formulate the desired form of the final solution.
+2. Update the artifact with the desired form of the final solution.
+3. `{{ donna.lib.goto("describe_solution_space") }}`
+
+## Describe solution space
+
+```toml donna
+id = "describe_solution_space"
+kind = "donna.lib.request_action"
+```
+
+To produce solution we should understand how to analyze the data and how to synthesize results into the final solution.
+
+For this we need to list the axes along which we will analyze the data and the dimensions along which we will synthesize the results.
+
+1. List the analysis axes.
+2. List the synthesis dimensions.
+3. Update the artifact with the description of the solution space.
+4. `{{ donna.lib.goto("describe_information_to_collect") }}`
+
+## Describe information to collect
+
+```toml donna
+id = "describe_information_to_collect"
+kind = "donna.lib.request_action"
+```
+
+1. Based on the formalized problem description and the list of goals, list the information to be collected to research the problem.
+2. Update the artifact with the description of the information to collect.
+3. `{{ donna.lib.goto("list_information_sources") }}`
+
+## List information sources
+
+```toml donna
+id = "list_information_sources"
+kind = "donna.lib.request_action"
+```
+
+1. Based on the formalized problem description and the list of goals, formulate a list of information sources that can help to research the problem.
+2. Update the artifact with the list of information sources.
+3. `{{ donna.lib.goto("collect_information") }}`
+
+## Collect information
+
+```toml donna
+id = "collect_information"
+kind = "donna.lib.request_action"
+```
+
+1. For each information source from the list:
+   1. For each piece of required information from the description:
+      1. If the source can not provide this piece of information, skip it.
+      2. Access the source and collect the required information.
+      3. Update the artifact with the collected information.
+2. `{{ donna.lib.goto("analyze_information") }}`
+
+## Analyze information
+
+```toml donna
+id = "analyze_information"
+kind = "donna.lib.request_action"
+```
+
+1. Using the analysis axes from the solution space description, analyze the collected information. Choose the format that best represents the analysis results and suits the the required solution form.
+2. Update the artifact with the analysis results.
+3. `{{ donna.lib.goto("synthesize_solutions") }}`
+
+## Synthesize solutions
+
+```toml donna
+id = "synthesize_solutions"
+kind = "donna.lib.request_action"
+```
+
+1. Using the synthesis dimensions from the solution space description, synthesize possible solutions based on the analysis results. Choose the format that best represents the synthesized solutions and suits the the required solution form.
+2. Update the artifact with the synthesized solutions.
+3. `{{ donna.lib.goto("evaluate_solutions") }}`
+
+## Evaluate solutions
+
+```toml donna
+id = "evaluate_solutions"
+kind = "donna.lib.request_action"
+```
+
+1. Evaluate the synthesized solutions against the goals from the formalized problem description.
+2. Update the artifact with the evaluation results.
+3. `{{ donna.lib.goto("produce_final_solution") }}`
+
+## Produce final solution
+
+```toml donna
+id = "produce_final_solution"
+kind = "donna.lib.request_action"
+```
+
+1. Based on the evaluation results, produce the final solution in the desired form.
+2. Update the artifact with the final solution.
+3. `{{ donna.lib.goto("finish") }}`
+
+## Finish
+
+```toml donna
+id = "finish"
+kind = "donna.lib.finish"
+```
+
+Research workflow completed. Provide the final research output to the developer.