diff --git a/docs/general/how-to-enable-scenario-creation-and-editing-on-dca-dev.md b/docs/general/how-to-enable-scenario-creation-and-editing-on-dca-dev.md new file mode 100644 index 0000000..8482cd2 --- /dev/null +++ b/docs/general/how-to-enable-scenario-creation-and-editing-on-dca-dev.md @@ -0,0 +1,153 @@ +# How to Enable Scenario Creation and Editing on `dca-dev` + +## Overview + +This guide outlines the proposed approach for enabling create, read, update, and delete (CRUD) operations on scenarios in the `dca-dev` environment. It summarizes the design direction discussed in Slack and identifies open questions that must be resolved before implementation. + +## Prerequisites + +The following are implied prerequisites for implementing scenario CRUD on `dca-dev`: + +- Access to the **Distillery** service (the system currently responsible for scenarios). +- Ability to modify or extend the **Distillery** data model (e.g., adding new tables). +- Access to and permission to modify the **`dca-dev` database**. +- Front-end development capability to: + - Add user interfaces (UI) for creating and managing tools. + - Add UI for creating and managing scenario “stubs.” +- Back-end development capability to: + - Define and expose APIs for scenario CRUD. + - Integrate with the database schema for tools and stubs. +- Understanding of existing **routines** and their **raw JSON** representations, as scenarios are expected to follow a similar pattern. + +> Note: No specific commands, URLs, or file paths were provided in the Slack discussion. These will need to be defined during implementation. + +## Proposed Design and Implementation Approach + +### 1. Enable CRUD Operations in Distillery + +To create or edit scenarios on `dca-dev`, Distillery must support full CRUD operations for scenarios: + +- **Create**: Define new scenarios and persist them. +- **Read**: Retrieve existing scenarios for viewing and execution. +- **Update**: Modify existing scenarios (e.g., change associated tools, stubs, or behavior). +- **Delete**: Remove scenarios that are no longer needed. + +This likely requires: + +- New or updated API endpoints in Distillery for scenario management. +- Authentication/authorization rules for who can perform scenario CRUD. + +### 2. Store Scenarios and Stubs in the Database + +The current thinking is to move scenario-related configuration from static or ad-hoc storage into a structured database model: + +1. **Tool Table** + - Represents tools used in scenarios. + - Each tool record contains metadata and configuration required for the tool to be invoked in a scenario. + +2. **Stub Table** + - Represents mocked behavior or responses associated with tools. + - Each stub row is linked to a tool via a **foreign key**. + - A stub defines how a tool should respond under specific conditions (e.g., given certain arguments). + +3. **Scenario Representation** + - Scenarios should have a **raw JSON representation**, similar to how routines are currently stored. + - A scenario is expected to: + - Reference one or more tools. + - Reference one or more stubs (or stub configurations) to define expected behavior. + - Some scenarios are more complex and may require: + - Multiple tools per scenario. + - Conditional behavior based on input arguments (e.g., “for these arguments return A, for different arguments return B”). + +> Open question: The exact database schema for scenarios (e.g., `scenarios` table, join tables between `scenarios` and `tools`, and how to store conditional logic) is not yet defined. + +### 3. Front-End User Interface Requirements + +To make scenario creation and editing possible on `dca-dev`, the front end must provide: + +1. **Tool Management UI** + - Create new tools. + - View and edit existing tools. + - Delete tools (if allowed). + +2. **Stub Management UI** + - For a given tool, create one or more stub rows. + - Define conditions (e.g., input arguments) and expected responses. + - Edit and delete stubs. + +3. **Scenario Management UI** + - Create new scenarios by: + - Selecting one or more tools. + - Associating the relevant stubs. + - Defining scenario metadata and behavior as raw JSON (or via a structured form that generates JSON). + - Edit existing scenarios (including tool and stub associations). + - Delete scenarios. + +### 4. Support for Complex and Workflow Scenarios + +The design must account for: + +- **Complex scenarios**: + - Scenarios that involve multiple tools. + - Scenarios where behavior varies based on input arguments (e.g., “mock bill changed” behavior). +- **Workflow scenarios**: + - Scenarios used specifically to test workflows. + - These should be **decoupled** from workflows themselves, meaning: + - Scenarios are defined independently. + - Workflows reference scenarios rather than embedding scenario logic directly. + +## Important Notes and Caveats + +- **Incomplete Specification**: The Slack discussion provides a conceptual direction but not a full specification. The following are not yet defined: + - Exact database schema (tables, columns, relationships). + - API contracts (endpoints, request/response formats). + - Authentication and authorization model for scenario editing. + - Any environment-specific configuration for `dca-dev` (e.g., database connection strings, feature flags). + +- **Behavioral Complexity**: + - Some scenarios require conditional mocking based on arguments. This may need: + - A structured way to define conditions (e.g., JSONPath, simple expression language). + - A clear precedence/override model when multiple stubs match. + +- **Parity with Routines**: + - Scenarios should follow the same pattern as routines with **raw JSON versions**, but the exact format and validation rules for scenario JSON are not yet specified. + +## Troubleshooting and Open Questions + +Because this is a design-level summary, troubleshooting is mostly about clarifying requirements and design before implementation: + +1. **Scenarios Not Editable on `dca-dev`** + - Confirm: + - Distillery has scenario CRUD endpoints implemented. + - The `dca-dev` environment is configured to use the new database tables. + - Front-end UI for tools, stubs, and scenarios is deployed and wired to the APIs. + +2. **Scenarios Not Behaving as Expected** + - Check: + - The scenario’s raw JSON is valid and conforms to the agreed schema. + - The correct tools and stubs are linked to the scenario. + - Stub conditions (arguments, matching rules) are correctly defined. + +3. **Data Model Ambiguities** + - Clarify: + - How many tools can be linked to a single scenario (one vs many). + - How to represent “for these args return A, for other args return B” in the database and JSON. + - Whether workflow-specific scenarios need additional metadata or types. + +4. **Additional Information Needed** + - A finalized **database schema** for: + - `tools` + - `stubs` + - `scenarios` + - Any join tables (e.g., `scenario_tools`, `scenario_stubs`). + - Detailed **API specifications** for: + - Creating, reading, updating, and deleting tools, stubs, and scenarios. + - **Front-end design** and UX flows for: + - Scenario creation/editing. + - Tool and stub management. + - Any **environment-specific details** for `dca-dev`: + - Base URLs for Distillery APIs. + - Feature flags or configuration toggles to enable scenario editing. + +--- +*Source: [Original Slack thread](https://distylai.slack.com/archives/impl-tower-think-tank/p1752207491518779)*