@crownpeak/dqm-react-component-dev-mcp 1.2.0

package/data/probe/examples/chat/README.md

@@ -0,0 +1,338 @@
+# Probe Chat
+
+A command-line and web interface for interacting with Probe code search using AI models through the Vercel AI SDK.
+
+## Features
+
+- Interactive CLI chat interface
+- Web-based chat interface with Markdown and syntax highlighting
+- Support for Anthropic Claude, OpenAI, and Google Gemini models
+- Force provider option to specify which AI provider to use
+- Semantic code search using Probe's search capabilities
+- AST-based code querying for finding specific code structures
+- Code extraction for viewing complete context
+- Session-based search caching for improved performance
+- Token usage tracking
+- Colorized output for better readability (CLI mode)
+- Diagram generation with Mermaid.js (Web mode)
+
+## Prerequisites
+
+- Node.js 18 or higher
+- Probe CLI installed and available in your PATH
+- An API key for Anthropic Claude, OpenAI, or Google Gemini
+
+## Installation
+
+1. Clone the repository
+2. Navigate to the `examples/chat` directory
+3. Install dependencies:
+
+```bash
+npm install
+```
+
+4. Create a `.env` file with your API keys:
+
+```
+# API Keys (uncomment and add your key)
+ANTHROPIC_API_KEY=your_anthropic_api_key
+# OPENAI_API_KEY=your_openai_api_key
+# GOOGLE_API_KEY=your_google_api_key
+
+# Force a specific provider (optional)
+# FORCE_PROVIDER=anthropic  # Options: anthropic, openai, google
+
+# Debug mode (set to true for verbose logging)
+DEBUG=false
+
+# Default model (optional)
+# For Anthropic: MODEL_NAME=claude-3-7-sonnet-latest
+# For OpenAI: MODEL_NAME=gpt-4o-2024-05-13
+# For Google: MODEL_NAME=gemini-2.0-flash
+
+# API URL configuration (optional)
+# Generic base URL for all providers (if provider-specific URL not set)
+# LLM_BASE_URL=https://your-custom-endpoint.com
+# Provider-specific URLs (override LLM_BASE_URL)
+# ANTHROPIC_API_URL=https://your-anthropic-endpoint.com
+# OPENAI_API_URL=https://your-openai-endpoint.com
+# GOOGLE_API_URL=https://your-google-endpoint.com
+
+# Folders to search (comma-separated list of paths)
+# If not specified, the current directory will be used by default
+# ALLOWED_FOLDERS=/path/to/folder1,/path/to/folder2
+
+# Web interface settings (optional)
+# PORT=8080
+# AUTH_ENABLED=false
+# AUTH_USERNAME=admin
+# AUTH_PASSWORD=password
+```
+
+## Usage
+
+### CLI Mode
+
+Start the chat interface in CLI mode:
+
+```bash
+node index.js
+```
+
+Or with npm:
+
+```bash
+npm start
+```
+
+### Web Mode
+
+Start the chat interface in web mode:
+
+```bash
+node index.js --web
+```
+
+Or with npm:
+
+```bash
+npm run web
+```
+
+You can specify a custom port:
+
+```bash
+node index.js --web --port 3000
+```
+
+You can also specify a path to the codebase you want to search:
+
+```bash
+node index.js /path/to/codebase
+```
+
+For example, to search in a repository located at ../../tyk:
+
+```bash
+node index.js ../../tyk
+```
+
+This will override any ALLOWED_FOLDERS setting in your .env file.
+
+### Command-line Options
+
+- `-d, --debug`: Enable debug mode for verbose logging
+- `-m, --model <model>`: Specify the model to use (e.g., `claude-3-7-sonnet-latest`, `gpt-4o-2024-05-13`, `gemini-2.0-flash`)
+- `-f, --force-provider <provider>`: Force a specific provider (options: `anthropic`, `openai`, `google`)
+- `-w, --web`: Run in web interface mode
+- `-p, --port <port>`: Port to run web server on (default: 8080)
+- `--prompt <value>`: Use a custom prompt (values: `architect`, `code-review`, `support`, or path to a file)
+- `[path]`: Path to the codebase to search (overrides ALLOWED_FOLDERS)
+
+### Special Commands
+
+During the chat, you can use these special commands:
+
+- `exit` or `quit`: End the chat session
+- `usage`: Display token usage statistics
+- `clear`: Clear the chat history and start a new session
+
+## How It Works
+
+This CLI tool uses the Vercel AI SDK to interact with AI models and provides them with tools to search and analyze your codebase:
+
+1. **search**: Searches code using Elasticsearch-like query syntax
+2. **query**: Searches code using AST-based pattern matching
+3. **extract**: Extracts code blocks from files with context
+
+The AI is instructed to use these tools to answer your questions about the codebase, providing relevant code snippets and explanations.
+
+### Search Caching
+
+The tool automatically generates a unique session ID for each chat session and passes it to the Probe CLI commands using the `--session` parameter. This enables caching of search results within a session, which can significantly improve performance when similar searches are performed multiple times.
+
+The session ID is managed internally and doesn't require any user intervention. When you start a new chat session (or use the "clear" command), a new session ID is generated, and a new cache is created.
+
+## Provider Options
+
+Probe Chat supports multiple AI providers, giving you flexibility in choosing which model to use for your code search and analysis:
+
+### Supported Providers
+
+1. **Anthropic Claude**
+   - Default model: `claude-3-7-sonnet-latest`
+   - Environment variable: `ANTHROPIC_API_KEY`
+   - Best for: Complex code analysis, detailed explanations, and understanding nuanced patterns
+
+2. **OpenAI GPT**
+   - Default model: `gpt-4o-2024-05-13`
+   - Environment variable: `OPENAI_API_KEY`
+   - Best for: General code search, pattern recognition, and concise explanations
+
+3. **Google Gemini**
+   - Default model: `gemini-2.0-flash`
+   - Environment variable: `GOOGLE_API_KEY`
+   - Best for: Fast responses, code generation, and efficient search
+
+### Forcing a Specific Provider
+
+You can force Probe Chat to use a specific provider in two ways:
+
+1. **Using the command line option**:
+   ```bash
+   node index.js --force-provider anthropic
+   node index.js --force-provider openai
+   node index.js --force-provider google
+   ```
+
+2. **Using the environment variable**:
+   Add this to your `.env` file:
+   ```
+   FORCE_PROVIDER=anthropic  # or openai, google
+   ```
+
+When forcing a provider, Probe Chat will verify that you have the corresponding API key set. If the API key is missing, it will display an error message.
+
+### Customizing Models
+
+You can specify which model to use for each provider:
+
+1. **Using the command line option**:
+   ```bash
+   node index.js --model claude-3-7-sonnet-latest
+   node index.js --model gpt-4o-2024-05-13
+   node index.js --model gemini-2.0-flash
+   ```
+
+2. **Using the environment variable**:
+   Add this to your `.env` file:
+   ```
+   MODEL_NAME=claude-3-7-sonnet-latest
+   ```
+
+Note that the model must be compatible with the selected provider. If you force a specific provider and specify a model, the model must be available for that provider.
+
+### Custom API Endpoints
+
+You can configure custom API endpoints for each provider:
+
+1. **Generic endpoint for all providers**:
+   ```
+   LLM_BASE_URL=https://your-custom-endpoint.com
+   ```
+   This will be used for all providers unless a provider-specific URL is set.
+
+2. **Provider-specific endpoints**:
+   ```
+   ANTHROPIC_API_URL=https://your-anthropic-endpoint.com
+   OPENAI_API_URL=https://your-openai-endpoint.com
+   GOOGLE_API_URL=https://your-google-endpoint.com
+   ```
+   These override the generic LLM_BASE_URL for their respective providers.
+Provider-specific URLs always take precedence over the generic LLM_BASE_URL.
+
+## Custom Prompts
+
+Probe Chat allows you to customize the system prompt used by the AI assistant. This can be useful for tailoring the assistant's behavior to specific use cases or domains.
+
+### Predefined Prompts
+
+By default, Probe Chat uses a "Code Explorer" prompt that's optimized for answering questions about code, explaining how systems work, and providing insights into code functionality.
+
+The `--prompt` option accepts several predefined prompt types to specialize the assistant for different tasks:
+
+1. **code-explorer** (default): Focuses on explaining and navigating code. The assistant will provide clear explanations of how code works, find relevant snippets, and trace function calls and data flow.
+
+   ```bash
+   node index.js --prompt code-explorer
+   ```
+   
+   Note: This is the default behavior, so you don't need to specify this prompt explicitly.
+
+2. **architect**: Focuses on software architecture and design. The assistant will analyze code from an architectural perspective, identify patterns, suggest improvements, and create high-level design documentation.
+
+   ```bash
+   node index.js --prompt architect
+   ```
+
+2. **code-review**: Focuses on code quality and best practices. The assistant will identify issues, suggest improvements, and ensure code follows best practices.
+
+   ```bash
+   node index.js --prompt code-review
+   ```
+
+3. **support**: Focuses on troubleshooting and problem-solving. The assistant will help diagnose errors, understand unexpected behaviors, and find solutions.
+
+   ```bash
+   node index.js --prompt support
+   ```
+
+Each predefined prompt type maintains the core functionality of Probe Chat while specializing in a particular area of focus. The standard instructions for using tools and following the XML format are automatically included with all predefined prompts.
+
+### Custom Prompt Files
+
+You can also provide a path to a file containing your own custom prompt:
+
+```bash
+node index.js --prompt /path/to/your/prompt.txt
+```
+
+The file should contain the complete system prompt that you want to use. This completely replaces the default system prompt. If you're creating a custom prompt, make sure to include instructions for using the available tools and following the XML format.
+
+Example custom prompt file:
+
+```
+You are ProbeChat Custom, a specialized AI assistant for [your specific use case].
+You focus on [specific area of expertise] and excel at [key strengths].
+
+Follow these instructions carefully:
+1.  Analyze the user's request with a focus on [your specific focus area].
+2.  Use <thinking></thinking> tags to analyze the situation and determine the appropriate tool for each step.
+3.  Use the available tools step-by-step to fulfill the request.
+4.  Ensure to get really deep and understand the full picture before answering.
+5.  You MUST respond with exactly ONE tool call per message, using the specified XML format, until the task is complete.
+6.  Wait for the tool execution result (provided in the next user message in a <tool_result> block) before proceeding to the next step.
+7.  Once the task is fully completed, and you have confirmed the success of all steps, use the '<attempt_completion>' tool to provide the final result.
+8.  Prefer concise and focused search queries. Use specific keywords and phrases to narrow down results.
+9.  [Add any additional specialized instructions here]
+```
+
+### Environment Variables
+
+You can also set a default prompt type using the environment variable:
+
+```
+PROMPT_TYPE=architect
+```
+
+Or specify a path to a custom prompt file:
+
+```
+CUSTOM_PROMPT=/path/to/your/prompt.txt
+```
+
+The command-line option takes precedence over the environment variable.
+Provider-specific URLs always take precedence over the generic LLM_BASE_URL.
+
+## Example Queries
+
+- "How does the config loading work?"
+- "Show me all RPC handlers"
+- "What does the process_file function do?"
+- "Find all implementations of the extract tool"
+- "Show me the main entry point of the application"
+
+## Architecture
+
+- `index.js`: Main entry point for both CLI and web interfaces
+- `probeChat.js`: Core chat functionality
+- `webServer.js`: Web server implementation
+- `auth.js`: Authentication middleware for web interface
+- `probeTool.js`: Tool definitions for code search, query, and extraction
+- `tokenCounter.js`: Utility for tracking token usage
+- `index.html`: Web interface HTML template
+
+## License
+
+Apache-2.0 

package/data/probe/examples/chat/TRACING.md

@@ -0,0 +1,226 @@
+# Tracing Support for Probe Chat
+
+This document describes the tracing functionality available in the Probe Chat application.
+
+## Overview
+
+Probe Chat now supports OpenTelemetry tracing for AI model calls, allowing you to:
+- Track AI model interactions and performance
+- Export traces to files for analysis
+- Send traces to remote OpenTelemetry collectors
+- Debug AI model calls with console output
+
+## Configuration
+
+### CLI Options
+
+You can enable tracing using the following command-line options:
+
+```bash
+# Enable file tracing (default: ./traces.jsonl)
+node index.js --trace-file
+
+# Enable file tracing with custom path
+node index.js --trace-file ./my-traces.jsonl
+
+# Enable remote tracing (default: http://localhost:4318/v1/traces)
+node index.js --trace-remote
+
+# Enable remote tracing with custom endpoint
+node index.js --trace-remote http://my-collector:4318/v1/traces
+
+# Enable console tracing for debugging
+node index.js --trace-console
+
+# Enable multiple exporters
+node index.js --trace-file --trace-remote --trace-console
+```
+
+### Environment Variables
+
+You can also configure tracing using environment variables:
+
+```bash
+# Enable file tracing
+export OTEL_ENABLE_FILE=true
+export OTEL_FILE_PATH=./traces.jsonl
+
+# Enable remote tracing
+export OTEL_ENABLE_REMOTE=true
+export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces
+
+# Enable console tracing
+export OTEL_ENABLE_CONSOLE=true
+
+# Service information
+export OTEL_SERVICE_NAME=probe-chat
+export OTEL_SERVICE_VERSION=1.0.0
+```
+
+## Trace Data
+
+The tracing system captures the following information:
+
+### Span Attributes
+- **Service Information**: Service name, version
+- **Session Information**: Session ID, iteration number
+- **Model Information**: Model name, API type (anthropic, openai, google)
+- **Configuration**: Allow edit flag, prompt type
+- **Function ID**: Unique identifier for each chat function
+
+### Trace Content
+- AI model requests and responses
+- Token usage statistics
+- Tool call information
+- Error details when they occur
+
+## File Format
+
+When using file tracing, traces are saved in JSON Lines format (`.jsonl`), where each line contains a complete trace span:
+
+```json
+{
+  "traceId": "abcd1234...",
+  "spanId": "efgh5678...",
+  "name": "ai.generateText",
+  "startTimeUnixNano": 1704067200000000000,
+  "endTimeUnixNano": 1704067201000000000,
+  "attributes": {
+    "sessionId": "session-123",
+    "iteration": "1",
+    "model": "claude-3-7-sonnet-20250219",
+    "apiType": "anthropic"
+  },
+  "status": { "code": "OK" },
+  "events": [],
+  "links": [],
+  "resource": {
+    "attributes": {
+      "service.name": "probe-chat",
+      "service.version": "1.0.0"
+    }
+  }
+}
+```
+
+## Remote Tracing
+
+For remote tracing, you can use any OpenTelemetry-compatible collector:
+
+### Using OpenTelemetry Collector
+
+1. Install the OpenTelemetry Collector
+2. Configure it with a `receiver` for OTLP HTTP
+3. Configure exporters for your preferred backend (Jaeger, Zipkin, etc.)
+
+Example collector config:
+
+```yaml
+receivers:
+  otlp:
+    protocols:
+      http:
+        endpoint: 0.0.0.0:4318
+
+exporters:
+  jaeger:
+    endpoint: jaeger:14250
+    tls:
+      insecure: true
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      exporters: [jaeger]
+```
+
+### Using Jaeger
+
+You can send traces directly to Jaeger using the OTLP endpoint:
+
+```bash
+# Start Jaeger
+docker run -d --name jaeger \
+  -p 16686:16686 \
+  -p 14250:14250 \
+  -p 14268:14268 \
+  -p 4317:4317 \
+  -p 4318:4318 \
+  jaegertracing/all-in-one:latest
+
+# Run probe-chat with remote tracing
+node index.js --trace-remote http://localhost:4318/v1/traces
+```
+
+## Example Usage
+
+### Basic File Tracing
+
+```bash
+# Enable file tracing and run a query
+node index.js --trace-file --message "What files are in this project?"
+
+# Check the generated traces
+cat traces.jsonl | jq '.'
+```
+
+### Remote Tracing with Jaeger
+
+```bash
+# Start Jaeger
+docker run -d --name jaeger -p 16686:16686 -p 4318:4318 jaegertracing/all-in-one:latest
+
+# Run probe-chat with remote tracing
+node index.js --trace-remote --message "Analyze the main function"
+
+# View traces at http://localhost:16686
+```
+
+### Combined Tracing
+
+```bash
+# Enable both file and remote tracing
+node index.js --trace-file ./debug-traces.jsonl --trace-remote http://localhost:4318/v1/traces --trace-console
+
+# This will:
+# 1. Save traces to ./debug-traces.jsonl
+# 2. Send traces to the remote collector
+# 3. Print traces to console for debugging
+```
+
+## Performance Considerations
+
+- **File Tracing**: Minimal overhead, suitable for production
+- **Remote Tracing**: Slight network overhead, depends on collector performance
+- **Console Tracing**: Higher overhead, recommended for debugging only
+
+## Integration with Vercel AI SDK
+
+The tracing system integrates with the Vercel AI SDK's experimental telemetry feature. When tracing is enabled, the SDK automatically:
+
+- Creates spans for each AI model call
+- Captures request/response data
+- Records token usage information
+- Tracks tool calls and their results
+
+## Troubleshooting
+
+### Common Issues
+
+1. **File permissions**: Ensure write permissions for the trace file directory
+2. **Remote collector unavailable**: Check network connectivity and collector status
+3. **Large trace files**: Consider log rotation for long-running sessions
+
+### Debug Mode
+
+Enable debug mode to see tracing initialization messages:
+
+```bash
+node index.js --debug --trace-file
+```
+
+This will show:
+- Telemetry initialization status
+- Exporter configuration
+- Any errors during setup