agent-generator 1.0.1 → 1.0.3

package/.github/agents/Generators.agent.md

@@ -0,0 +1,121 @@
+---
+name: GeneratorAgent
+description: Creates generators using the OpenAPI specification and defined generator patterns. Ensures all generators are made correctly, efficiently, and according to requirements.
+---
+
+## Role
+Responsible for building generators that follow strict rules and guidelines based on OpenAPI and specified patterns.
+
+---
+
+## What to do
+
+1. Read all generator type definitions in the Generator_Patterns folder to understand their rules and structures, then use them to create generators based on the OAS file’s schema and dependencies.
+
+2. Analyze the user prompt to identify only the dependencies explicitly requested by the user. Do not add extra setup dependencies on your own.
+
+3. For user-requested dependencies, ensure generators extract the required values from API responses so downstream generators can consume them clearly and correctly.
+
+4. Always create a new generator file instead of modifying existing ones. If you need to modify or add to an existing generator, request explicit user permission before proceeding.
+
+5. Refer to the `PathConfig.properties` file to find the paths for OAS files and existing generator files. Always use these paths when reading or referencing OAS or generator files.
+
+6. Use only the dependencies explicitly provided in the user prompt. Do not include every parameter listed in the OAS, and do not auto-create additional dependency generators unless the user explicitly asks.
+
+7.  Any parameter you use must be explicitly defined in that OAS operation (body, query, path, header). Never invent fields, wrapper keys, or placeholders. Use only parameters explicitly mentioned in the user prompt and ignore all other parameters.
+
+8. You may use tools if necessary to generate the generators correctly.
+---
+
+## Generator
+
+1. Generator names must use snake_case (all lowercase, underscores), be clear, consistent, and meaningful, matching the resource and purpose. Use singular for single values (e.g., entity_id), plural for lists (e.g., entity_ids). All generator names must be unique and kept short and meaningful.
+
+2. Maintain order in generator creation based on dependencies. If Generator A depends on Generator B, ensure that Generator B is created before Generator A.
+
+3. Ensure that all generators strictly follow the definitions and rules specified in the generator type definition files.
+
+4. Choose the correct generator type strictly according to its definition file.
+
+5. For the "name" field inside a generator, use the resource name from PathConfig in snake_case: plural for lists, singular for single items (e.g., "resources", "resource", "records").
+
+6. Follow exact reference syntax, dataPath format, and structural rules as defined in the type definition files and README.md.
+
+7.  Output must contain only the "generators" JSON object.
+
+8.  When using short-hand references like `$departments` or `$contacts`, ensure they reference generators defined in the same `test_data_generation_configurations.json` file unless the reference explicitly uses a relative cross-file path (for example `../Department/...`). This prevents accidental cross-file name collisions and keeps generated params local by default.
+
+9. Operation ID format: Always specify `generatorOperationId` using the `<service>.<Entity>.<operation>` pattern (for example: "generatorOperationId": "support.Agent.getAgents").
+
+10. When params are used in a dynamic generator, the parameter names should be the same as those defined in the OpenAPI specification.
+
+11. If you use param input from body, query, path or header, please make sure the reference path is correct and the field exists in the OpenAPI specification. For example: "$.input.body:$.ticketId" for request body, "$.input.query:$.status" for query parameter, "$.input.path:$.agentId" for path parameter, "$.input.header:$.Authorization" for header.
+
+12. If the same API with the same payload is needed more than once, call that API only once, store the entire response object, and extract all required values from that stored response.
+
+13. When storing an entire object in a generator, the `dataPath` must use the `:$` format (for example: `$.response.body:$`).
+
+---
+
+## Generator Structure Rule
+
+All generators must be created using the following structure:
+
+```json
+{
+    "generators": {
+        "<generator_name>": [
+        {}
+        ]
+    }
+}
+```
+
+- All dependencies for a generator must be included in the same array under the generator name.
+- This ensures clarity, maintainability, and proper grouping of related generator steps.
+- Generator name should be descriptive of the entity and purpose, following the snake_case convention.
+---
+
+## Generator Creation Rules
+
+1. Create subfolder with PascalCase name (e.g., `CreateContact`, `CreateTicket`) in `Created_Generators` directory, add `test_data_generation_configurations.json` inside.
+
+2. Only create the generator JSON file.
+
+3. Always create new generator files instead of modifying existing ones. Request explicit permission before editing existing generators.
+
+---
+
+## Prompt Handling Rules
+
+1. **Direct Prompt**: When user provides a direct prompt (e.g., "Create Contact", "Create Ticket"), implement the generator immediately without preamble like "Create generator for X".
+
+2. **Explicit Request**: When user explicitly says "Create a generator for X" or similar, proceed as normal with full context.
+
+3. **Skip Explanation**: For direct prompts, go straight to building the generator, no explanations.
+
+4. **Clarify Ambiguity First**: If there is any confusion about which generator to use, which data to extract, or how required values should be sourced, ask the user first and generate only after confirmation.
+
+5. **No Implicit Body Defaults**: For implied actions (for example, "add comments"), do not auto-fill request body fields that were not provided in the prompt. Ask the user for missing values first.
+
+6. **Optional Param Choice**: In ambiguous enum/choice situations, ask the user with available options and include one extra option: **"Don't consider this param"**. If the user selects it, omit that parameter from the generator.
+
+---
+
+## Do Not:
+
+1. Don't Invent new generator types or modify existing rules.
+
+2. Don't modify or generate any section other than "generators" in the test_data_generation_configurations.json file.
+
+3. Don't include explanations, comments, markdown, or extra text in the final output.
+
+4. Don't edit OpenAPI specification files.
+
+5. Never include any param or field in a generator unless it is explicitly defined in the OAS for that operation.
+
+6. Don't auto-add setup generators (for example Contact/Department/Account) unless those dependencies are explicitly requested by the user.
+
+7. Don't ask permission for read access to OAS or generator files, as you have full access to read any file in the specified paths.You have permission to read files outside of the workspace.
+
+8. Don't give text response in chat window.Only output the generator JSON object as specified.

package/.github/copilot-instructions.md

@@ -0,0 +1,19 @@
+# Generator Agent
+
+You are a Generator Agent responsible for generating conditional rule-based data.
+
+## Capabilities
+
+- Generate static data based on fixed values
+- Generate dynamic data using expressions and functions
+- Generate conditional data based on rules
+- Generate reference data from other fields
+- Generate remote data from external APIs
+
+## Instructions
+
+When a user asks to generate data:
+1. Ask what type of generation they need (static, dynamic, conditional, reference, or remote)
+2. Understand the data structure requirements
+3. Generate appropriate configuration based on the patterns
+4. Provide clear examples and explanations

package/Generator_Patterns/Conditional.md

@@ -0,0 +1,84 @@
+# CONDITIONAL Generator — Rule-Based Data Selection
+
+---
+
+## Overview
+
+A **Conditional Generator** selects a data generator based on predefined conditions. It enables dynamic test data generation by evaluating input values or context and branching to different generator logic accordingly.
+
+---
+
+## When to Use
+
+- When the value of a parameter depends on other input values or request context.
+- To implement business rules, feature flags, or scenario-specific data.
+- For fallback/default logic when no condition matches.
+
+---
+
+## Structure
+
+A conditional generator contains:
+- `type`: Must be `"conditional"`
+- `conditions`: List of condition objects, each with:
+	- `when`: The condition to evaluate (key, operator, value)
+	- `then`: The generator or value to use if the condition matches
+- `else`: (optional) The generator or value to use if no conditions match
+
+---
+
+## Example
+
+```json
+{
+	"generators": {
+		"snippet_id": [
+			{
+				"type": "conditional",
+				"conditions": [
+					{
+						"when": {
+							"key": "$.input.query:modules",
+							"equals": "tickets"
+						},
+						"then": {
+							"use": "$generators:#/generators/ticket_id"
+						}
+					},
+					{
+						"when": {
+							"key": "$.input.query:modules",
+							"equals": "contacts"
+						},
+						"then": {
+							"use": "$generators:#/generators/contact_id"
+						}
+					}
+				],
+				"else": "$generators:#/generators/activity_id"
+			}
+		]
+	}
+}
+```
+
+---
+
+## Best Practices
+
+- Use input-based branching: reference request path, query, or body fields in `when`.
+- Reference other generators in `then` using correct relative paths or `$generators:` syntax.
+- Always provide an `else` clause if possible to avoid unexpected nulls.
+- Keep conditions mutually exclusive and clear.
+- Avoid deeply nested or overly complex chains for readability.
+
+---
+
+## Validation Checklist
+
+- Ensure all referenced generators exist.
+- Test each condition path for expected output.
+
+---
+
+*Last Updated: 17 February 2026*

package/Generator_Patterns/Dynamic.md

@@ -0,0 +1,129 @@
+
+# Rule: Referencing Single-Entity Dynamic Generator Dependencies
+
+When a dynamic generator is used as a dependency for another generator (e.g., createTicket), always reference the dependency in params as $<generatorname>.value, regardless of the dataPath used in the dependency generator. This ensures the correct value is passed even if the dataPath returns an array or a single value.
+
+**Example:**
+
+Dependency generator:
+```json
+{
+  "type": "dynamic",
+  "name": "departments",
+  "generatorOperationId": "support.Department.getDepartments",
+  "dataPath": "$.response.body:$.data[*].id"
+}
+```
+
+Dependent generator:
+```json
+{
+  "type": "dynamic",
+  "name": "ticket",
+  "generatorOperationId": "support.Ticket.createTicket",
+  "params": {
+    "departmentId": "$departments.value"
+  }
+}
+```
+
+## What It Does
+A DYNAMIC Generator fetches data from real API responses.
+
+---
+
+## When to Use DYNAMIC
+- When you need real system data that changes frequently (e.g., active agent IDs, current ticket IDs).
+- When there is an API available to fetch the required data.
+  
+---
+
+## Required Properties
+
+| Property | Type | Purpose |
+|----------|------|---------|
+| `type` | string | Must be `"dynamic"` |
+| `generatorOperationId` | string | Which API operation to call |
+| `dataPath` | string | Where to extract data from response |
+
+## Optional Properties
+
+| Property | Type | Purpose |
+|----------|------|---------|
+| `params` | object | Filter parameters: `{"status": "ACTIVE"}` |
+| `name` | string | Generator identifier (unique label for referencing in params) |
+
+---
+
+## DataPath Format
+
+**Pattern:** `$.response.body:$.path.to.data`
+
+**Examples:**
+- `$.response.body:$.data[0].id` - First item ID
+- `$.response.body:$.data[*].id` - All item IDs
+- `$.response.body:$.items[0].manager.id` - Nested field
+
+---
+
+## Examples
+
+### Single Result
+Fetch the first matching record:
+```json
+{
+  "type": "dynamic",
+  "generatorOperationId": "support.Agent.getAgents",
+  "dataPath": "$.response.body:$.data[0].id"
+}
+```
+### With Filter Parameters
+Find specific records:
+```json
+{
+  "type": "dynamic",
+  "generatorOperationId": "support.Agent.getAgents",
+  "dataPath": "$.response.body:$.data[*].id",
+  "params": {"status": "ACTIVE"}
+}
+```
+### Nested Field
+Extract from object hierarchy:
+```json
+{
+  "type": "dynamic",
+  "generatorOperationId": "support.Department.getDepartment",
+  "dataPath": "$.response.body:$.manager.id"
+}
+```
+---
+
+## Best Practices
+
+**Do:**
+- Use params to filter for specific scenarios
+- Give descriptive names showing the filter/status
+- Verify operationId exists in OpenAPI specification
+  
+**Avoid:**
+- Assuming first result is always valid
+- Generic names like "id"
+- Forgetting `[*]` on array parameters
+- Hardcoding fallback without DYNAMIC
+  
+---
+
+## Check
+- operationId is spelled correctly
+- dataPath matches actual response structure
+- params filter isn't too strict
+
+## Reference
+- **Fetch Method:** API operations
+- **Data Type:** Real system data
+- **Scope:** Cross-entity references possible
+- **Updates:** Auto-syncs with system data
+
+---
+
+*Last Updated: 17 February 2026*

package/Generator_Patterns/PathConfig.properties

@@ -0,0 +1,4 @@
+
+# Path configurations for generator framework (using source folder)
+GENERATOR_CONFIG_PATH=../source/api-data-generators/support/
+OAS_FILE_PATH=../source/openapi-specifications/v1.0/support/

package/Generator_Patterns/README.md

@@ -0,0 +1,118 @@
+# Data Generation Framework
+
+## What is this?
+
+This framework helps you generate test data for APIs defined in OpenAPI (OAS) files.
+
+In simple words:
+- You define generators in JSON.
+- Generators call APIs, reuse values, and build input data.
+- You can chain generators when one value depends on another.
+
+## What is a generator?
+
+A generator is a small JSON step that produces data.
+
+Examples:
+- Fetch `departmentId` from an API response
+- Reuse a value from request input
+- Set a fixed value like `priority = "high"`
+
+All generators must be inside the `generators` object.
+
+Basic format:
+
+```json
+{
+  "generators": {
+    "generator_name": [
+      {
+        "type": "..."
+      }
+    ]
+  }
+}
+```
+
+## About the Generator Agent
+
+The Generator Agent helps developers create generator files faster and correctly.
+
+The agent does the following:
+- Reads the target operation from OAS
+- Finds required dependencies from related operations
+- Creates generator steps in the correct dependency order
+- Uses only fields that exist in OAS (no invented params)
+- Produces output in the required `generators` JSON structure
+
+## Where to find paths
+
+Use `PathConfig.properties` as the source of truth:
+- `GENERATOR_CONFIG_PATH` for generator file locations
+- `OAS_FILE_PATH` for OpenAPI specification locations
+
+Always use these configured paths instead of hardcoding paths.
+
+## Generator types
+
+Use the right type based on your need:
+
+| Type | Purpose | Documentation |
+| --- | --- | --- |
+| Dynamic | Get values from API operations | [Dynamic](./Dynamic.md) |
+| Remote | Get values from system/remote helpers | [Remote](./Remote.md) |
+| Static | Use fixed constant values | [Static](./Static.md) |
+| Reference | Reuse existing values from input/other generators | [Reference](./Reference.md) |
+| Conditional | Choose values based on conditions | [Conditional](./Conditional.md) |
+
+## JSONPath quick guide
+
+Common response mapping format:
+
+`$.location:$.path`
+
+Examples:
+- `$.data[*].id` → all ids in an array
+- `$.data[0].id` → first id
+- `$.manager.id` → nested value
+- `$.users[?(@.active == true)].id` → filtered values
+
+## Developer workflow (quick)
+
+1. Identify the target API operation.
+2. Read the target operation in OAS.
+3. Identify dependency operations and required values.
+4. Choose proper generator types.
+5. Create a new generator file in the correct folder.
+6. Keep dependencies in order inside the same generator array.
+7. Validate all params and paths against OAS.
+
+## Important rules
+
+- Use snake_case generator names.
+- Keep names meaningful and short.
+- Use singular for single value, plural for list values.
+- Do not add fields that are not present in OAS.
+- Do not modify existing generators unless explicitly requested.
+
+## Reference Syntax
+
+```
+$<generatorname>.value                    // Generator reference
+$.input.body:$.fieldName                  // Request body
+$.input.query:$.paramName                 // Query parameter
+$.input.path:$.pathParam                  // URL path
+$.input.header:$.HeaderName               // HTTP header
+```
+
+## DataPath Format
+
+```
+$.response.body:$.data[0].id              // First item ID
+$.response.body:$.data[*].id              // All item IDs
+$.response.body:$.id                      // Direct ID field
+$.response.body:$.manager.id              // Nested field
+$.response.body:$.items[?(@.status == 'active')].id  // Filtered values
+```
+
+Last updated: 23 February 2026

package/Generator_Patterns/Reference.md

@@ -0,0 +1,98 @@
+# REFERENCE Generator - Use Request Input Data
+
+## What It Does
+
+Passes data directly from incoming request to response without modification. Extracts values from request body, query parameters, path parameters, or headers.
+
+---
+
+## When to Use REFERENCE
+
+Use REFERENCE when:
+A Reference Generator extracts data from previous API responses.- Using data from request body
+- Getting values from query parameters
+- Using path parameters
+- Using header values
+- Data comes directly from request
+
+**Common Scenarios:**
+- Pass ticket ID from request to response
+- Use query parameters in operations
+- Extract URL path parameters
+- Forward authorization headers
+- Use nested request objects
+
+---
+
+## Required Properties
+
+| Property | Type | Purpose |
+|----------|------|---------|
+| `type` | string | Must be `"reference"` |
+| `ref` | string | Path to request data |
+
+## Reference Path Format
+
+**Pattern:** `$.input.{location}:$.{jsonPath}`
+
+### Location Types
+
+| Location | Source | Example |
+|----------|--------|---------|
+| `$.input.body` | Request body JSON | `$.input.body:$.ticketId` |
+| `$.input.query` | Query parameters | `$.input.query:$.departmentId` |
+| `$.input.path` | URL path parameters | `$.input.path:$.ticketId` |
+| `$.input.header` | HTTP headers | `$.input.header:$.Authorization` |
+
+### Path Selector Examples
+
+| Reference | Extracts |
+|-----------|----------|
+| `$.input.body:$.fieldName` | Simple field from body |
+| `$.input.body:$.parent.child.fieldName` | Nested field |
+| `$.input.body:$.items[*].id` | All array IDs |
+| `$.input.body:$.items[0].id` | First array ID |
+| `$.input.query:$.parameterName` | Query parameter |
+| `$.input.path:$.pathParamName` | Path parameter |
+| `$.input.header:$.HeaderName` | Header value |
+
+---
+
+## Best Practices
+
+**Do:**
+- Verify request contains the fields you reference
+- Use exact field names (case-sensitive)
+- Use clear generator names matching source
+
+**Avoid:**
+- Referencing fields that don't exist
+- Assuming request structure without docs
+- Using REFERENCE for static values
+- Ignoring case sensitivity
+
+---
+
+## When to Use REFERENCE
+
+| Scenario | Use REFERENCE |
+|----------|---|
+| Pass-through from request | Yes |
+| Get data from request | Yes |
+| Fetch from database | No |
+| Fixed constant | No |
+| System timestamp | No |
+| Logic-based value | No |
+
+---
+
+## Reference
+
+- **Fetch Method:** Request fields
+- **Data Type:** Request data (pass-through)
+- **Scope:** Single request scope
+- **Updates:** From request content
+
+---
+
+*Last Updated: 17 February 2026*