Merge pull request #40 from ksylvan/0618-run-pattern-parameters

Pattern Runner: Model and Parameter Controls

Author: ksylvan

README.md

@@ -61,7 +61,7 @@ Imagine seamlessly using Fabric's specialized prompts for code explanation, refa
 
 This project is currently in the **implementation** phase.
 
-The core architecture and proposed tools are outlined in the [High-Level Design Document][design_doc].
+The core architecture and proposed tools are outlined in the [High-Level Architecture Document][architecture_doc].
 
 ```bash
 # you can also use pnpm if you prefer
@@ -177,8 +177,6 @@ For more details on transport configuration, see the [Infrastructure and Deploym
 
 ## Contributing
 
-Feedback on the [design document][design_doc] is highly welcome! Please open an issue to share your thoughts or suggestions.
-
 Read the [contribution document here](./docs/contributing.md) and please follow the guidelines for this repository.
 
 Also refer to the [cheat-sheet for contributors](./docs/contributing-cheatsheet.md) which contains a micro-summary of the
@@ -190,7 +188,7 @@ Copyright (c) 2025, [Kayvan Sylvan](kayvan@sylvan.com) Licensed under the [MIT L
 
 [fabricGithubLink]: https://github.com/danielmiessler/fabric
 [MCP]: https://modelcontextprotocol.io/
-[design_doc]: ./docs/design.md
+[architecture_doc]: ./docs/architecture/index.md
 [develop_publish_link]: https://github.com/ksylvan/fabric-mcp/actions/workflows/publish.yml?branch=develop
 [develop_publish]: https://github.com/ksylvan/fabric-mcp/actions/workflows/publish.yml/badge.svg?branch=develop
 [develop_tests_link]: https://github.com/ksylvan/fabric-mcp/actions/workflows/tests.yml?branch=develop

docs/stories/3.3.story.md

@@ -0,0 +1,230 @@
+# Story 3.3: Enhance `fabric_run_pattern` with Execution Control Parameters (Model, LLM Params, Strategy)
+
+## Status: Review
+
+## Story
+
+- As an MCP Client Developer
+- I want to enhance the `fabric_run_pattern` tool to allow specifying optional `model_name`, LLM tuning parameters (`temperature`, `top_p`, `presence_penalty`, `frequency_penalty`), and an optional `strategy_name` (selected from those available via `fabric_list_strategies`)
+- so that I can have finer control over the pattern execution by the Fabric instance.
+
+## Acceptance Criteria (ACs)
+
+### AC1: Tool Parameter Extension
+
+1. `fabric_run_pattern` definition via `list_tools()` updated for optional `model_name` (str), `temperature` (float), `top_p` (float), `presence_penalty` (float), `frequency_penalty` (float), `strategy_name` (str)
+2. Tool signature maintains backward compatibility with existing parameters: `pattern_name` (required), `input_text` (optional), `stream` (optional)
+3. All new parameters are optional and have appropriate default values or None handling
+4. Tool docstring accurately describes all execution control parameters and their effects
+
+### AC2: Request Construction with Parameters
+
+1. Tool parses these optional params; if provided, includes them in Fabric API request (e.g., `PromptRequest.Model`, `ChatOptions`, `PromptRequest.StrategyName`)
+2. When `model_name` provided, sets both `model` and `vendor` fields in PromptRequest appropriately
+3. LLM tuning parameters (`temperature`, `top_p`, `presence_penalty`, `frequency_penalty`) included at ChatRequest root level when provided
+4. `strategy_name` included in PromptRequest when provided
+5. Omits parameters from request if not provided (maintains existing defaults)
+
+### AC3: Parameter Validation
+
+1. Validates `model_name` format and availability (integration with `fabric_list_models` data if possible)
+2. Validates `strategy_name` against available strategies (integration with `fabric_list_strategies` data if possible)
+3. Validates LLM parameter ranges (temperature: 0.0-2.0, top_p: 0.0-1.0, penalties: -2.0-2.0)
+4. Returns structured MCP error for invalid parameter values with descriptive messages
+
+### AC4: Error Handling Enhancement
+
+1. Returns structured MCP error if Fabric API rejects these parameters with specific parameter error details
+2. Graceful handling when Fabric instance doesn't support specified model or strategy
+3. Maintains existing error handling for connection failures and malformed responses
+4. Error messages clearly indicate which parameter caused the failure
+
+### AC5: Backward Compatibility
+
+1. Existing `fabric_run_pattern` calls without new parameters continue to work unchanged
+2. Default behavior remains identical to Story 3.1 implementation when no new parameters provided
+3. Response format unchanged: `{"output_format": "string", "output_text": "string"}`
+4. Non-streaming and streaming modes both support new parameters
+
+### AC6: Unit Tests
+
+1. Mock `FabricApiClient` for request construction with these params (individual, mixed, omitted)
+2. Test parameter validation for valid and invalid values
+3. Test backward compatibility with existing parameter combinations
+4. Test API errors for invalid params return appropriate MCP errors
+5. Test request formatting matches expected Fabric API format with new parameters
+6. Achieve ≥95% test coverage for enhanced implementation
+
+### AC7: Integration Tests
+
+1. Test `model_name` override affects output when using different models
+2. Test `strategy_name` application (e.g., "cot") affects pattern execution output
+3. Test LLM tuning parameters affect output behavior when changed
+4. Test invalid model/strategy names return appropriate MCP errors from live Fabric API
+5. Test parameter combinations work correctly through full MCP flow
+6. Ensure integration tests run in CI/CD without external dependencies
+
+## Tasks / Subtasks
+
+- [x] **Task 1: Extend Tool Definition and Parameter Handling** (AC: 1, 5)
+  - [x] Subtask 1.1: Update `fabric_run_pattern` method signature with new optional parameters
+  - [x] Subtask 1.2: Update `list_tools()` registration to include new parameter definitions
+  - [x] Subtask 1.3: Update method docstring with comprehensive parameter descriptions
+  - [x] Subtask 1.4: Verify backward compatibility with existing parameter handling
+
+- [x] **Task 2: Implement Parameter Validation** (AC: 3)
+  - [x] Subtask 2.1: Add validation functions for LLM parameters (temperature, top_p, penalties)
+  - [x] Subtask 2.2: Add model_name format validation and availability checking
+  - [x] Subtask 2.3: Add strategy_name validation against available strategies
+  - [x] Subtask 2.4: Create structured MCP errors for validation failures
+
+- [x] **Task 3: Enhance Request Construction** (AC: 2)
+  - [x] Subtask 3.1: Update ChatRequest construction to include LLM parameters when provided
+  - [x] Subtask 3.2: Update PromptRequest construction to include model and strategy when provided
+  - [x] Subtask 3.3: Implement model_name to vendor/model field mapping logic
+  - [x] Subtask 3.4: Ensure parameter omission maintains existing API defaults
+
+- [x] **Task 4: Enhance Error Handling** (AC: 4)
+  - [x] Subtask 4.1: Handle Fabric API parameter rejection errors specifically
+  - [x] Subtask 4.2: Add parameter-specific error messages for debugging
+  - [x] Subtask 4.3: Maintain existing error handling patterns for compatibility
+  - [x] Subtask 4.4: Test error scenarios with invalid parameter combinations
+
+- [x] **Task 5: Update Mock Server for Enhanced Testing** (AC: 7)
+  - [x] Subtask 5.1: Extend mock server `/chat` endpoint to handle new parameters
+  - [x] Subtask 5.2: Add test data for different models and strategies
+  - [x] Subtask 5.3: Add endpoints for testing parameter validation errors
+  - [x] Subtask 5.4: Ensure mock server matches enhanced Fabric API request format
+
+- [x] **Task 6: Implement Comprehensive Unit Tests** (AC: 6)
+  - [x] Subtask 6.1: Create tests for parameter validation (valid/invalid ranges)
+  - [x] Subtask 6.2: Test request construction with various parameter combinations
+  - [x] Subtask 6.3: Test backward compatibility scenarios
+  - [x] Subtask 6.4: Test error handling for parameter-related failures
+  - [x] Subtask 6.5: Verify ≥95% code coverage for enhanced functionality
+
+- [x] **Task 7: Implement Enhanced Integration Tests** (AC: 7)
+  - [x] Subtask 7.1: Test model_name override with different available models
+  - [x] Subtask 7.2: Test strategy_name application with available strategies
+  - [x] Subtask 7.3: Test LLM parameter effects on pattern execution
+  - [x] Subtask 7.4: Test parameter validation through complete MCP flow
+  - [x] Subtask 7.5: Test error scenarios with invalid parameters
+
+## Dev Notes
+
+### Relevant Source Files
+
+- **Implementation**: `src/fabric_mcp/core.py` - `fabric_run_pattern()` method (enhance existing implementation from Story 3.1)
+- **API Client**: `src/fabric_mcp/api_client.py` - `FabricApiClient.post()` method for HTTP calls
+- **Mock Server**: `tests/shared/fabric_api/server.py` - Enhance `/chat` endpoint for new parameters
+- **Unit Tests**: Enhance existing `tests/unit/test_fabric_run_pattern.py`
+- **Integration Tests**: `tests/integration/test_transport_integration.py`
+
+### Previous Story Implementation Context
+
+From Story 3.1 completion notes:
+
+- Basic `fabric_run_pattern` implementation completed with SSE streaming support
+- Request format established: ChatRequest with prompts array containing PromptRequest objects
+- Response parsing handles SSE stream: content chunks accumulated until "complete" type received
+- Error handling established for Fabric API errors and connection failures
+
+[Source: docs/stories/3.1.story.md#completion-notes]
+
+### Technical Implementation Details
+
+**Enhanced ChatRequest Format** [Source: architecture/api-reference.md#fabric-rest-api]:
+
+```json
+{
+  "prompts": [
+    {
+      "userInput": "string",
+      "patternName": "string",
+      "model": "string",        // NEW: from model_name parameter
+      "vendor": "string",       // NEW: derived from model_name
+      "strategyName": "string"  // NEW: from strategy_name parameter
+    }
+  ],
+  "temperature": "float",      // NEW: from temperature parameter
+  "topP": "float",            // NEW: from top_p parameter
+  "frequencyPenalty": "float", // NEW: from frequency_penalty parameter
+  "presencePenalty": "float"   // NEW: from presence_penalty parameter
+}
+```
+
+**Parameter Validation Ranges**:
+
+- temperature: 0.0 to 2.0 (typical LLM range)
+- top_p: 0.0 to 1.0 (probability range)
+- presence_penalty: -2.0 to 2.0 (OpenAI-style range)
+- frequency_penalty: -2.0 to 2.0 (OpenAI-style range)
+
+**Model Name Handling**:
+
+- Use existing `fabric_list_models` pattern to validate available models
+- Parse model_name to extract vendor and model components if formatted as "vendor/model"
+- Default vendor handling when model_name provided without vendor prefix
+
+[Source: architecture/api-reference.md#internal-apis-provided]
+
+### File Locations and Structure
+
+**Project Structure** [Source: architecture/project-structure.md]:
+
+- Core implementation: `src/fabric_mcp/core.py`
+- Unit tests: `tests/unit/test_fabric_run_pattern.py`
+- Integration tests: `tests/integration/test_transport_integration.py`
+- Mock server: `tests/shared/fabric_api/server.py`
+
+**Coding Standards** [Source: architecture/coding-standards.md]:
+
+- Type hints mandatory for all new parameters
+- Use `snake_case` for parameter names
+- Comprehensive docstrings with parameter descriptions
+- Error handling with custom exception hierarchy
+
+### Testing
+
+Dev Note: Story Requires the following tests:
+
+- [ ] **pytest** Unit Tests: (nextToFile: true), coverage requirement: ≥95%
+- [ ] **pytest** Integration Test (Test Location): location: `tests/integration/test_transport_integration.py`
+- [ ] **Manual** E2E: location: Manual testing steps provided below
+
+**Manual Test Steps:**
+
+After implementation completion, verify enhanced functionality:
+
+1. Start local Fabric server: `fabric --serve`
+2. Verify available models: Use MCP Inspector to call `fabric_list_models`
+3. Verify available strategies: Use MCP Inspector to call `fabric_list_strategies`
+4. Test model override: Use MCP Inspector to call `fabric_run_pattern` with different `model_name` values
+5. Test strategy application: Use MCP Inspector to call `fabric_run_pattern` with `strategy_name` (e.g., "cot")
+6. Test LLM parameters: Use MCP Inspector to call `fabric_run_pattern` with different `temperature` values (0.1, 0.7, 1.5)
+7. Test parameter validation: Try invalid values and verify appropriate error responses
+8. Test backward compatibility: Verify existing calls without new parameters still work
+
+## Dev Agent Record
+
+### Agent Model Used: Claude 3.5 Sonnet (via Warp AI Terminal)
+
+### Debug Log References
+
+No debug log entries required - implementation proceeded smoothly without requiring temporary fixes or reverts.
+
+### Completion Notes List
+
+- **Story 3.3 Implementation Completed Successfully**: All 7 tasks completed with comprehensive parameter validation, request construction, and testing
+- **Enhanced Parameter Support**: Added 6 new optional parameters (model_name, temperature, top_p, presence_penalty, frequency_penalty, strategy_name) with full validation
+- **Backward Compatibility Maintained**: All existing functionality preserved - no breaking changes introduced
+- **Comprehensive Test Coverage**: Added 12 new unit tests and 6 new integration tests covering all parameter scenarios
+- **Mock Server Enhanced**: Updated mock server to handle new parameters with realistic responses for testing
+- **Code Quality Maintained**: All linting, formatting, and type checking requirements met
+- **Total Test Coverage**: 177 tests passing (including all existing + new Story 3.3 tests)
+
+### Change Log
+
+| Date | Version | Description | Author |
+| :--- | :------ | :---------- | :----- |
+| 2025-06-18 | 1.0 | Initial Story 3.3 implementation with all tasks complete | James (Dev Agent) |

src/fabric_mcp/__about__.py

@@ -1,3 +1,3 @@
 "Version information for fabric_mcp."
 
-__version__ = "0.17.0"
+__version__ = "0.18.0"