mirror of
https://github.com/eyaltoledano/claude-task-master.git
synced 2025-07-30 20:34:19 +00:00
245c3cb398
This commit introduces a standardized pattern for capturing and propagating AI usage telemetry (cost, tokens, model used) across the Task Master stack and applies it to the 'add-task' functionality. Key changes include: - **Telemetry Pattern Definition:** - Added defining the integration pattern for core logic, direct functions, MCP tools, and CLI commands. - Updated related rules (, , Usage: mcp [OPTIONS] COMMAND [ARGS]... MCP development tools ╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ version Show the MCP version. │ │ dev Run a MCP server with the MCP Inspector. │ │ run Run a MCP server. │ │ install Install a MCP server in the Claude desktop app. │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯, , ) to reference the new telemetry rule. - **Core Telemetry Implementation ():** - Refactored the unified AI service to generate and return a object alongside the main AI result. - Fixed an MCP server startup crash by removing redundant local loading of and instead using the imported from for cost calculations. - Added to the object. - ** Integration:** - Modified (core) to receive from the AI service, return it, and call the new UI display function for CLI output. - Updated to receive from the core function and include it in the payload of its response. - Ensured (MCP tool) correctly passes the through via . - Updated to correctly pass context (, ) to the core function and rely on it for CLI telemetry display. - **UI Enhancement:** - Added function to to show telemetry details in the CLI. - **Project Management:** - Added subtasks 77.6 through 77.12 to track the rollout of this telemetry pattern to other AI-powered commands (, , , , , , ). This establishes the foundation for tracking AI usage across the application.
103 lines
7.1 KiB
Plaintext
103 lines
7.1 KiB
Plaintext
---
|
|
description: Guidelines for interacting with the unified AI service layer.
|
|
globs: scripts/modules/ai-services-unified.js, scripts/modules/task-manager/*.js, scripts/modules/commands.js
|
|
---
|
|
|
|
# AI Services Layer Guidelines
|
|
|
|
This document outlines the architecture and usage patterns for interacting with Large Language Models (LLMs) via Task Master's unified AI service layer (`ai-services-unified.js`). The goal is to centralize configuration, provider selection, API key management, fallback logic, and error handling.
|
|
|
|
**Core Components:**
|
|
|
|
* **Configuration (`.taskmasterconfig` & [`config-manager.js`](mdc:scripts/modules/config-manager.js)):**
|
|
* Defines the AI provider and model ID for different **roles** (`main`, `research`, `fallback`).
|
|
* Stores parameters like `maxTokens` and `temperature` per role.
|
|
* Managed via the `task-master models --setup` CLI command.
|
|
* [`config-manager.js`](mdc:scripts/modules/config-manager.js) provides **getters** (e.g., `getMainProvider()`, `getParametersForRole()`) to access these settings. Core logic should **only** use these getters for *non-AI related application logic* (e.g., `getDefaultSubtasks`). The unified service fetches necessary AI parameters internally based on the `role`.
|
|
* **API keys** are **NOT** stored here; they are resolved via `resolveEnvVariable` (in [`utils.js`](mdc:scripts/modules/utils.js)) from `.env` (for CLI) or the MCP `session.env` object (for MCP calls). See [`utilities.mdc`](mdc:.cursor/rules/utilities.mdc) and [`dev_workflow.mdc`](mdc:.cursor/rules/dev_workflow.mdc).
|
|
|
|
* **Unified Service (`ai-services-unified.js`):**
|
|
* Exports primary interaction functions: `generateTextService`, `generateObjectService`. (Note: `streamTextService` exists but has known reliability issues with some providers/payloads).
|
|
* Contains the core `_unifiedServiceRunner` logic.
|
|
* Internally uses `config-manager.js` getters to determine the provider/model/parameters based on the requested `role`.
|
|
* Implements the **fallback sequence** (e.g., main -> fallback -> research) if the primary provider/model fails.
|
|
* Constructs the `messages` array required by the Vercel AI SDK.
|
|
* Implements **retry logic** for specific API errors (`_attemptProviderCallWithRetries`).
|
|
* Resolves API keys automatically via `_resolveApiKey` (using `resolveEnvVariable`).
|
|
* Maps requests to the correct provider implementation (in `src/ai-providers/`) via `PROVIDER_FUNCTIONS`.
|
|
* Returns a structured object containing the primary AI result (`mainResult`) and telemetry data (`telemetryData`). See [`telemetry.mdc`](mdc:.cursor/rules/telemetry.mdc) for details on how this telemetry data is propagated and handled.
|
|
|
|
* **Provider Implementations (`src/ai-providers/*.js`):**
|
|
* Contain provider-specific wrappers around Vercel AI SDK functions (`generateText`, `generateObject`).
|
|
|
|
**Usage Pattern (from Core Logic like `task-manager/*.js`):**
|
|
|
|
1. **Import Service:** Import `generateTextService` or `generateObjectService` from `../ai-services-unified.js`.
|
|
```javascript
|
|
// Preferred for most tasks (especially with complex JSON)
|
|
import { generateTextService } from '../ai-services-unified.js';
|
|
|
|
// Use if structured output is reliable for the specific use case
|
|
// import { generateObjectService } from '../ai-services-unified.js';
|
|
```
|
|
|
|
2. **Prepare Parameters:** Construct the parameters object for the service call.
|
|
* `role`: **Required.** `'main'`, `'research'`, or `'fallback'`. Determines the initial provider/model/parameters used by the unified service.
|
|
* `session`: **Required if called from MCP context.** Pass the `session` object received by the direct function wrapper. The unified service uses `session.env` to find API keys.
|
|
* `systemPrompt`: Your system instruction string.
|
|
* `prompt`: The user message string (can be long, include stringified data, etc.).
|
|
* (For `generateObjectService` only): `schema` (Zod schema), `objectName`.
|
|
|
|
3. **Call Service:** Use `await` to call the service function.
|
|
```javascript
|
|
// Example using generateTextService (most common)
|
|
try {
|
|
const resultText = await generateTextService({
|
|
role: useResearch ? 'research' : 'main', // Determine role based on logic
|
|
session: context.session, // Pass session from context object
|
|
systemPrompt: "You are...",
|
|
prompt: userMessageContent
|
|
});
|
|
// Process the raw text response (e.g., parse JSON, use directly)
|
|
// ...
|
|
} catch (error) {
|
|
// Handle errors thrown by the unified service (if all fallbacks/retries fail)
|
|
report('error', `Unified AI service call failed: ${error.message}`);
|
|
throw error;
|
|
}
|
|
|
|
// Example using generateObjectService (use cautiously)
|
|
try {
|
|
const resultObject = await generateObjectService({
|
|
role: 'main',
|
|
session: context.session,
|
|
schema: myZodSchema,
|
|
objectName: 'myDataObject',
|
|
systemPrompt: "You are...",
|
|
prompt: userMessageContent
|
|
});
|
|
// resultObject is already a validated JS object
|
|
// ...
|
|
} catch (error) {
|
|
report('error', `Unified AI service call failed: ${error.message}`);
|
|
throw error;
|
|
}
|
|
```
|
|
|
|
4. **Handle Results/Errors:** Process the returned text/object or handle errors thrown by the unified service layer.
|
|
|
|
**Key Implementation Rules & Gotchas:**
|
|
|
|
* ✅ **DO**: Centralize **all** LLM calls through `generateTextService` or `generateObjectService`.
|
|
* ✅ **DO**: Determine the appropriate `role` (`main`, `research`, `fallback`) in your core logic and pass it to the service.
|
|
* ✅ **DO**: Pass the `session` object (received in the `context` parameter, especially from direct function wrappers) to the service call when in MCP context.
|
|
* ✅ **DO**: Ensure API keys are correctly configured in `.env` (for CLI) or `.cursor/mcp.json` (for MCP).
|
|
* ✅ **DO**: Ensure `.taskmasterconfig` exists and has valid provider/model IDs for the roles you intend to use (manage via `task-master models --setup`).
|
|
* ✅ **DO**: Use `generateTextService` and implement robust manual JSON parsing (with Zod validation *after* parsing) when structured output is needed, as `generateObjectService` has shown unreliability with some providers/schemas.
|
|
* ❌ **DON'T**: Import or call anything from the old `ai-services.js`, `ai-client-factory.js`, or `ai-client-utils.js` files.
|
|
* ❌ **DON'T**: Initialize AI clients (Anthropic, Perplexity, etc.) directly within core logic (`task-manager/`) or MCP direct functions.
|
|
* ❌ **DON'T**: Fetch AI-specific parameters (model ID, max tokens, temp) using `config-manager.js` getters *for the AI call*. Pass the `role` instead.
|
|
* ❌ **DON'T**: Implement fallback or retry logic outside `ai-services-unified.js`.
|
|
* ❌ **DON'T**: Handle API key resolution outside the service layer (it uses `utils.js` internally).
|
|
* ⚠️ **generateObjectService Caution**: Be aware of potential reliability issues with `generateObjectService` across different providers and complex schemas. Prefer `generateTextService` + manual parsing as a more robust alternative for structured data needs.
|