commit dae09dd6fe28f2ef5acb87e204a0def757559b9a Author: Zhongwei Li Date: Sun Nov 30 09:02:51 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..609c922 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,14 @@ +{ + "name": "field-agent-skills", + "description": "Field Agent development and production best practices including deployment workflows, documentation standards, and professional Plotly visualization guidelines for creating executive-ready agents", + "version": "0.0.0-2025.11.28", + "author": { + "name": "Treasure Data", + "email": "support@treasuredata.com" + }, + "skills": [ + "./skills/deployment", + "./skills/documentation", + "./skills/visualization" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..6a04534 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# field-agent-skills + +Field Agent development and production best practices including deployment workflows, documentation standards, and professional Plotly visualization guidelines for creating executive-ready agents diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..535a64a --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,52 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:treasure-data/td-skills:field-agent-skills", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "b86c8e42daebe4f10779f2ffdb870cf8945006e0", + "treeHash": "0808db7b9c18d211984ca374b76e11cb36bec9f4e1771129f6ee0a61a69b80cb", + "generatedAt": "2025-11-28T10:28:45.983288Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "field-agent-skills", + "description": "Field Agent development and production best practices including deployment workflows, documentation standards, and professional Plotly visualization guidelines for creating executive-ready agents" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "dc316dc37daa4c7de35c1b67f397f0fd203a385f415dfbfcee1e103e2176b011" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "a0e95ddcad9519784fca9370724b7d8c091698bb7b9f42aa62bdc5b652e6dad3" + }, + { + "path": "skills/visualization/SKILL.md", + "sha256": "6a1327c4093856ff7073d508567b9c4b1302db1032302738e8e264bca470c3ba" + }, + { + "path": "skills/documentation/SKILL.md", + "sha256": "15172106046def68342d2a03bb47583e493c1c23cd22629e758f6459406fdf65" + }, + { + "path": "skills/deployment/SKILL.md", + "sha256": "ac8b1844695020c42278934bd75c58bb5dff08f3eab57b6846010c56dce8f696" + } + ], + "dirSha256": "0808db7b9c18d211984ca374b76e11cb36bec9f4e1771129f6ee0a61a69b80cb" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/deployment/SKILL.md b/skills/deployment/SKILL.md new file mode 100644 index 0000000..783ee54 --- /dev/null +++ b/skills/deployment/SKILL.md @@ -0,0 +1,422 @@ +--- +name: field-agent-deployment +description: Best practices for developing, testing, and deploying production-ready Field Agents including R&D workflows, version control, testing strategies, and release management +--- + +# Field Agent Deployment Best Practices + +This skill provides comprehensive guidelines for the complete lifecycle of Field Agent development and deployment, from initial R&D through production release. + +## When to Use This Skill + +Use this skill when you need help with: +- Setting up a Field Agent development workflow +- Structuring a Field Agent project for production +- Creating deployment pipelines for Field Agents +- Implementing testing strategies for Field Agents +- Publishing and releasing Field Agent updates +- Managing Field Agent environments (dev, staging, prod) + +## Development Workflow + +### R&D Phase Best Practices + +#### 1. Project Initiation +Before starting new agent development: + +```markdown +## Pre-Development Checklist +- [ ] Validate use case and business requirements +- [ ] Review existing agent catalog to avoid duplication +- [ ] Get stakeholder approval for new agent development +- [ ] Document initial requirements and expected outcomes +- [ ] Set up team communication channel +- [ ] Publish initial draft documentation to alert team +``` + +#### 2. Environment Strategy + +**Development Environments:** +- R&D can occur in any development environment +- Production deployment requires dedicated production instance +- Use environment variables for instance-specific configurations + +## Production Publishing Workflow + +### Step-by-Step Publishing Process + +#### Phase 1: Preparation +```markdown +1. Code Freeze + - Ensure all features are complete and tested + - No new features during release cycle + - Bug fixes only with approval + +2. Quality Gates + - All unit tests passing + - Integration tests successful + - Performance benchmarks met + - Security scan completed + - Documentation updated +``` + +#### Phase 2: Pre-Release Testing + +**End-to-End Testing Checklist:** +```markdown +- [ ] Test all primary use cases in staging environment +- [ ] Verify tool integrations and data access +- [ ] Validate error handling and edge cases +- [ ] Test with various input formats and user prompts +- [ ] Verify output format consistency +- [ ] Check resource usage (iterations, tokens, runtime) +- [ ] Test timeout and failure scenarios +- [ ] Validate permissions and access control +``` + +#### Phase 3: Production Deployment + +**Deployment Checklist:** +```markdown +## Pre-Deployment +- [ ] Clone/update production repository +- [ ] Export agent configuration from staging +- [ ] Review and validate all configuration files +- [ ] Verify README.md is complete and accurate +- [ ] Check environment-specific variables + +## Database & Dependencies +- [ ] Migrate required databases to production instance +- [ ] Verify table schemas match expectations +- [ ] Validate data access permissions +- [ ] Test external API connections +- [ ] Confirm tool dependencies are available + +## Deployment +- [ ] Push agent to production instance +- [ ] Verify agent appears in production catalog +- [ ] Test agent activation and loading +- [ ] Run smoke tests in production +- [ ] Monitor initial executions for errors + +## Post-Deployment +- [ ] Record demo video of production usage +- [ ] Update documentation with production links +- [ ] Announce release to stakeholders +- [ ] Set up monitoring and alerting +- [ ] Schedule post-deployment review +``` + +**Deployment Script Template:** +```bash +#!/bin/bash +# deploy-agent.sh + +set -e # Exit on error + +AGENT_NAME="customer-segmentation-agent" +PROD_INSTANCE="prod-instance-id" +GITHUB_REPO="https://github.com/your-org/field-agents" + +echo "Starting deployment for ${AGENT_NAME}..." + +# Step 1: Clone/update repository +if [ -d "field-agents" ]; then + cd field-agents && git pull origin main && cd .. +else + git clone ${GITHUB_REPO} +fi + +# Step 2: Push to production (use your deployment tool) +echo "Deploying to production instance ${PROD_INSTANCE}..." +# TODO: Replace with your actual deployment command +# Example placeholder: td-agent-cli push --instance ${PROD_INSTANCE} --agent ${AGENT_NAME} +# For TD deployments, consult your infrastructure team for the correct deployment tool + +echo "Deployment completed successfully!" +``` + +## Documentation Standards + +### Required Documentation Components + +#### 1. README.md Template +```markdown +# [Agent Name] + +Brief one-line description of what this agent does. + +## Overview +Detailed description of agent purpose, capabilities, and business value. + +## Quick Start +\``` +# Example usage +[Show simplest possible usage example] +\``` + +## Features +- Feature 1: Description +- Feature 2: Description +- Feature 3: Description + +## Prerequisites +- Treasure Data instance access +- Required databases: [list databases] +- Required tools/integrations: [list tools] + +## Installation +Step-by-step installation instructions + +## Usage +Common usage patterns and examples + +## Configuration +Configuration options and parameters + +## Troubleshooting +Common issues and solutions + +## Contributing +Guidelines for contributions (if applicable) + +## License & Support +License information and support contacts +``` + +#### 2. Technical Documentation +```markdown +# [Agent Name] - Technical Documentation + +## Architecture Overview +High-level architecture diagram and component description + +## System Prompt +Link to or excerpt of system prompt + +## Tools & Functions +Detailed description of each tool: +- Function name +- Purpose +- Input parameters +- Output format +- Example usage + +## Data Flow +Describe how data flows through the agent + +## Performance Characteristics +- Average execution time +- Token usage patterns +- Resource requirements + +## Security & Permissions +Required permissions and security considerations + +## Version History +Major versions and changes +``` + +#### 3. Demo & Examples + +**Create Demo Content:** +```markdown +## Demo Video Requirements +- Length: 2-5 minutes +- Show: Primary use case walkthrough +- Include: Input prompt, execution, output +- Highlight: Key features and benefits +- Format: Screen recording with audio narration + +## Sample Conversations +Provide 3-5 example conversations: +1. Basic/common use case +2. Advanced use case with options +3. Error handling example +4. Edge case handling +5. Integration with other tools +``` + +## Release Management + +### Version Numbering + +Use semantic versioning (MAJOR.MINOR.PATCH): +``` +1.0.0 - Initial production release +1.1.0 - New feature added +1.1.1 - Bug fix +2.0.0 - Breaking change +``` + +### Release Notes Template + +```markdown +# Release Notes - v1.2.0 + +## Release Date +2024-11-15 + +## Summary +Brief overview of this release + +## New Features +- Feature 1: Description and benefit +- Feature 2: Description and benefit + +## Improvements +- Improvement 1: What was enhanced +- Improvement 2: Performance optimization details + +## Bug Fixes +- Fix 1: Issue resolved +- Fix 2: Error corrected + +## Breaking Changes +- Change 1: What changed and migration path +- Change 2: Required updates + +## Migration Guide +Step-by-step instructions for upgrading from previous version + +## Known Issues +- Issue 1: Workaround if available +- Issue 2: Expected fix timeline +``` + +### Communication Protocol + +**Release Announcement Template:** +```markdown +Subject: [RELEASED] [Agent Name] v1.2.0 - [Key Feature] + +Team, + +We've released version 1.2.0 of [Agent Name] to production. + +**Key Updates:** +• New feature: [Feature name and benefit] +• Improvement: [Performance/usability improvement] +• Bug fix: [Critical fix] + +**Links:** +• Production Agent: [link] +• Documentation: [link] +• Demo Video: [link] +• Release Notes: [link] + +**Action Required:** +[Any required actions for users/teams] + +**Support:** +For questions or issues, contact [support channel/person] + +Thanks, +[Your Name] +``` + +## Monitoring & Maintenance + +### Maintenance Schedule + +```markdown +## Regular Maintenance Tasks + +### Daily +- Review error logs +- Monitor execution metrics +- Check system health + +### Weekly +- Review performance trends +- Update documentation if needed +- Check for dependency updates + +### Monthly +- Security audit +- Performance optimization review +- User feedback collection and analysis +- Roadmap planning + +### Quarterly +- Major version planning +- Architecture review +- Disaster recovery testing +``` + +## Troubleshooting Guide + +### Common Deployment Issues + +```markdown +## Issue: Agent Not Appearing in Production + +**Symptoms:** Agent deployed but not visible in catalog + +**Possible Causes:** +1. Configuration file not properly formatted +2. Agent ID conflict with existing agent +3. Permissions not set correctly + +**Solutions:** +1. Validate JSON configuration files +2. Check for ID conflicts in production catalog +3. Verify production instance permissions + +## Issue: Tools Failing in Production + +**Symptoms:** Tools work in dev but fail in production + +**Possible Causes:** +1. Database not migrated to production +2. API credentials not configured +3. Network/firewall restrictions + +**Solutions:** +1. Verify database exists: `td db:list | grep [db_name]` +2. Check environment variables and secrets +3. Test network connectivity to external services + +## Issue: Poor Performance in Production + +**Symptoms:** Agent slower than expected + +**Possible Causes:** +1. Large dataset queries without optimization +2. Too many tool iterations +3. Inefficient system prompt + +**Solutions:** +1. Add query filters and limits +2. Reduce max_tool_iterations setting +3. Optimize system prompt for efficiency +``` + +## Best Practices Summary + +### Do's ✅ +- Always test thoroughly before production deployment +- Use version control for all agent components +- Document every configuration change +- Create comprehensive test suites +- Monitor production usage and errors +- Keep dependencies updated +- Follow semantic versioning +- Communicate releases to stakeholders + +### Don'ts ❌ +- Don't deploy untested changes to production +- Don't skip documentation updates +- Don't hardcode environment-specific values +- Don't deploy without backup/rollback plan +- Don't ignore error logs and metrics +- Don't make breaking changes without migration guide +- Don't deploy during peak usage hours without notice + +## Resources & Tools + +### Recommended Development Tools +- **Version Control:** Git with GitHub/GitLab +- **CI/CD:** GitHub Actions, GitLab CI, or Jenkins +- **Monitoring:** Application logging and metrics collection +- **Documentation:** Markdown with auto-generated API docs diff --git a/skills/documentation/SKILL.md b/skills/documentation/SKILL.md new file mode 100644 index 0000000..fd5b170 --- /dev/null +++ b/skills/documentation/SKILL.md @@ -0,0 +1,941 @@ +--- +name: field-agent-documentation +description: Comprehensive template and guidelines for documenting Field Agents including technical specifications, system prompts, tool specifications, user interactions, and standardized documentation structure +--- + +# Field Agent Documentation Standards + +This skill provides a complete template and best practices for creating professional, comprehensive documentation for Field Agents. Following these standards ensures consistency, clarity, and ease of use across all agent documentation. + +## When to Use This Skill + +Use this skill when you need to: +- Create documentation for a new Field Agent +- Standardize existing Field Agent documentation +- Write system prompts with best practices +- Define tool specifications and naming conventions +- Structure user prompts and interaction patterns +- Document agent architecture and technical details + +## Documentation Structure Overview + +Complete Field Agent documentation should include these sections in order: + +```markdown +1. Basic Information (metadata, links, status) +2. Team Structure (owners, contributors) +3. Purpose & Functionality (description, value, users) +4. Usage Scenarios (use cases, examples) +5. Technical Specifications (model, settings, parameters) +6. Dependencies & Integration (requirements, data sources) +7. Agent/Sub-Agent Details (per-agent specifications) +8. System Prompt (detailed agent instructions) +9. Tools (function specifications and schemas) +10. Input/Output Format (data structures, formats) +11. User Prompts (interaction patterns, guided flows) +12. Development Roadmap (milestones, phases) +13. Demo (examples, videos, recordings) +``` + +--- + +## Section 1: Basic Information + +This section provides essential metadata about the agent. + +### Template + +```markdown +# [Agent Name] + +## Basic Information + +| Item | Details | +|------|---------| +| **Project Name** | [Clean, self-explanatory, immutable name] | +| **Type** | Field Agent | +| **Interface Type** | TD Workflow / Chat / Slack / API | +| **GitHub Repo Link** | [Repository URL] | +| **Status** | Development / Staging / Production | +| **Version** | [Semantic version: MAJOR.MINOR.PATCH] | +| **Last Updated** | [YYYY-MM-DD] | +| **Agent Instance** | [Cloud provider: instance ID] | +| **Agent Link** | [Direct link to agent] | +| **One-Pager Slide** | [Link to overview presentation] | +| **Demo Video** | [Link to demonstration recording] | +| **Demo Talk-Track** | [Link to demo script] | +``` + +### Best Practices +- **Project Name**: Choose a clear, descriptive name that won't change +- **Status**: Keep status current (Development → Staging → Production) +- **Version**: Use semantic versioning (1.0.0, 1.1.0, 2.0.0) +- **Links**: Ensure all links are accessible to target audience + +--- + +## Section 2: Team Structure + +Document who is responsible for the agent. + +### Template + +```markdown +## Team Structure + +| Role | Assignee | +|------|----------| +| **Product Owner / Main Architect** | [Name, Email] | +| **Additional Contributors** | [Names, Roles] | +| **Support Contact** | [Team/Channel] | +``` + +### Best Practices +- Include contact information for support +- List all contributors for accountability +- Update when team changes occur + +--- + +## Section 3: Purpose & Functionality + +Explain what the agent does and why it matters. + +### Template + +```markdown +## Purpose & Functionality + +### Description +[Brief 2-3 sentence description of what the agent performs and its core functionality] + +### Key Capabilities +- **Integration 1**: [What it integrates with and how] +- **Integration 2**: [What it integrates with and how] +- **Core Feature**: [Primary capability description] + +### Business Value +[Explain the business value this agent delivers. What problems does it solve? What ROI does it provide?] + +### Target Users +- **Primary**: [Job roles/personas who will use this most] +- **Secondary**: [Additional users who may benefit] + +### Potential Applications +[Detailed description of who will use this agent and in what contexts] +``` + +### Example + +```markdown +## Purpose & Functionality + +### Description +Customer Segmentation Agent analyzes customer data to automatically identify behavioral segments using RFM (Recency, Frequency, Monetary) analysis and predictive modeling. + +### Key Capabilities +- **Database Integration**: Connects to Treasure Data customer databases +- **Segmentation Algorithms**: RFM, K-means clustering, behavioral scoring +- **Visualization**: Generates interactive Plotly charts and segment distributions + +### Business Value +Enables marketing teams to identify high-value customer segments 10x faster than manual analysis, improving campaign targeting accuracy by 35% and increasing ROI on marketing spend. + +### Target Users +- **Primary**: Marketing Managers, CRM Analysts, Customer Success Teams +- **Secondary**: Data Analysts, Business Intelligence Teams + +### Potential Applications +Marketing teams use this agent to create targeted campaigns, CRM teams identify at-risk customers for retention programs, and analysts explore customer lifetime value patterns. +``` + +--- + +## Section 4: Usage Scenarios + +Provide concrete examples of how the agent is used. + +### Template + +```markdown +## Usage Scenarios + +### Primary Use Case +[Describe the most common use case with a step-by-step example] + +**Example:** +1. User asks: "[Sample user query]" +2. Agent performs: "[What the agent does]" +3. Agent returns: "[What the user receives]" + +### Additional Use Cases +1. **Use Case Name**: [Description and benefit] +2. **Use Case Name**: [Description and benefit] +3. **Use Case Name**: [Description and benefit] + +### Example Scenarios + +#### Scenario 1: [Name] +**Context**: [When this scenario applies] +**User Input**: "[Example user query]" +**Agent Output**: [What the agent provides] +**Outcome**: [Business result] + +#### Scenario 2: [Name] +[Follow same structure] +``` + +--- + +## Section 5: Technical Specifications + +Define the technical configuration of the agent. + +### Template + +```markdown +## Technical Specifications + +| Item | Details | +|------|---------| +| **Agent Name** | [Name - use `[Sub]` prefix for sub-agents] | +| **Model Name** | Claude 4 Sonnet ⭐ (Recommended) / Claude 3.5 Sonnet / Claude 3 Haiku | +| **Max Tool Iterations** | [Number - controls resource consumption] | +| **Temperature** | [0-1, where 0 = deterministic, 1 = creative] ⭐ Recommended: 0 | +| **Max Tokens** | [Output token limit] | +| **Timeout** | [Execution timeout in seconds] | +``` + +### Model Selection Guide + +**Claude 4 Sonnet (Recommended)** ⭐ +- Best for: Most production Field Agents +- Benefits: Highest performance, more output tokens, better reasoning +- Use when: You need reliability and comprehensive outputs + +**Claude 3.5 Sonnet** +- Best for: Alternative to Claude 4, similar capabilities +- Benefits: Strong performance, widely tested +- Use when: Claude 4 not available or testing compatibility + +**Claude 3 Haiku** +- Best for: Lightweight, fast-response tasks +- Benefits: Lower cost, faster execution +- Use when: Simple queries, real-time requirements, budget constraints + +### Temperature Guide + +| Temperature | Behavior | Best For | +|-------------|----------|----------| +| **0** ⭐ | Deterministic, consistent answers | Most Field Agents, production use | +| **0.3** | Slight variation, mostly consistent | Agents needing minor creative variation | +| **0.7** | Balanced creativity and consistency | Content generation with some flexibility | +| **1.0** | Maximum creativity, varied outputs | Creative writing, brainstorming agents | + +**Recommended**: Use temperature **0** for Field Agents to ensure consistent, reliable outputs. + +### Max Tool Iterations + +Controls how many times the agent can execute tools before stopping. + +```markdown +- **Low (5-10)**: Simple agents with few tool calls +- **Medium (15-20)**: Most Field Agents with moderate complexity +- **High (25-30)**: Complex agents requiring multiple data sources and iterations +``` + +**Best Practice**: Start with 15-20, increase only if agent needs more steps. + +--- + +## Section 6: Dependencies & Integration + +Document all external requirements and integrations. + +### Template + +```markdown +## Dependencies & Integration + +### Required Data Sources +| Data Source | Purpose | Access Requirements | +|-------------|---------|---------------------| +| [Database/Table] | [What data is used] | [Permissions needed] | + +### Integration Points +| Integration | Type | Purpose | +|-------------|------|---------| +| [System/API] | [REST/GraphQL/SDK] | [What it's used for] | + +### Prerequisites +- [ ] Access to [database/system] +- [ ] Permissions: [specific permissions] +- [ ] API keys configured: [which APIs] +- [ ] Dependencies installed: [libraries/tools] + +### Dependencies on Other Systems +- [None] OR [List dependent workflows, features, product permissions] +``` + +### Example + +```markdown +## Dependencies & Integration + +### Required Data Sources +| Data Source | Purpose | Access Requirements | +|-------------|---------|---------------------| +| `customer_db.transactions` | Transaction history for RFM analysis | Read access to customer_db | +| `customer_db.profiles` | Customer demographic data | Read access to customer_db | + +### Integration Points +| Integration | Type | Purpose | +|-------------|------|---------| +| Treasure Data Trino | SQL Query | Data extraction and analysis | +| Plotly | Visualization Library | Chart generation | + +### Prerequisites +- [ ] Access to `customer_db` database +- [ ] Permissions: Read access on customer tables +- [ ] API keys configured: None required +- [ ] Dependencies installed: Plotly for visualizations + +### Dependencies on Other Systems +- Requires Treasure Data instance with Trino query engine +- No dependencies on external workflows +``` + +--- + +## Section 7: Agent/Sub-Agent Details + +Provide detailed specifications for each agent and sub-agent. + +### Template + +```markdown +## Agent Details: [Agent Name] + +| Item | Details | +|------|---------| +| **Agent Name** | [Name] or **[Sub] [Name]** for sub-agents | +| **Model Name** | Claude 4 Sonnet ⭐ | +| **Max Tool Iterations** | [Number] | +| **Temperature** | 0 ⭐ | +| **Purpose** | [What this specific agent does] | +| **Invocation** | [How this agent is called] | + +### Sub-Agents +If this agent uses sub-agents, list them: + +- **[Sub] Sub-Agent Name**: [Purpose and when it's invoked] +``` + +### Best Practices +- Use `[Sub]` prefix for sub-agents to distinguish from main agents +- Document invocation patterns (how/when sub-agents are called) +- Specify different configurations if sub-agents use different models + +--- + +## Section 8: System Prompt + +The system prompt is the most critical element - it defines agent behavior. + +### System Prompt Structure Template + +```markdown +## System Prompt: [Agent Name] + +# [Agent Name] + +[Brief one-line description of agent role and purpose] + +# Role + +The agent's role and responsibilities: +- [Responsibility 1] +- [Responsibility 2] +- [Responsibility 3] + +# Goal + +[Detailed description of what the user receives when the agent is executed and what the agent aims to achieve] + +## Basic Principles + +High-level workflow: +1. [Step 1: What happens first] +2. [Step 2: What happens next] +3. [Step 3: Final steps] +4. [Step 4: Output delivery] + +## Available Tools + +### [Tool Category/Purpose] + +**Tool**: `tool_name_in_snake_case` +**Purpose**: [Brief purpose of this tool] +**Input**: [What inputs the tool consumes] +**Output**: [What outputs the tool returns] + +### [Next Tool Category] + +**Tool**: `another_tool_name` +**Purpose**: [Brief purpose] +**Input**: [Input parameters] +**Output**: [Return values] + +## Task Flow + +### Task 1: [Tool Name] [required = true, mandatory_start = true] + +**Execution**: +call_[required = true, mandatory_start = true] + +**Steps** [sequential=true]: +1. [Detailed step-by-step pseudo-logic] +2. [What the tool should do] +3. [How to handle results] +4. [Error handling] + +**Output Format**: +[Describe or show sample output format] + +### Task 2: [Next Tool] [required = false] + +[Follow same structure] + +## Checklist (Optional) + +If applicable, provide a validation checklist: +- [ ] [Validation item 1] +- [ ] [Validation item 2] +- [ ] [Validation item 3] +``` + +### System Prompt Best Practices + +#### 1. Tool Naming Conventions ⭐ + +**Use snake_case with descriptive names:** + +✅ **Good Examples:** +``` +verify_database_access +list_columns_customer_db +query_sales_data +calculate_rfm_scores +generate_segment_visualization +fetch_customer_transactions +``` + +❌ **Bad Examples:** +``` +verify # Too vague +list # What are we listing? +query # Query what? +verifydbaccess # Hard to read, no separators +listColumns # Should be snake_case +``` + +**Naming Pattern**: `[action]_[object]_[context]` +- **Action**: verify, list, query, calculate, generate, fetch, create, update +- **Object**: database, columns, data, scores, visualization +- **Context**: customer_db, sales, rfm, etc. + +#### 2. Reduce Hallucination with Detailed Logic + +Provide explicit pseudo-logic instead of general instructions: + +✅ **Good - Explicit Logic:** +```markdown +### Task 1: Query Customer Data + +**Steps** [sequential=true]: +1. Call `verify_database_access` with database name +2. If access is denied, return error message: "Database access denied. Please check permissions." +3. If access is granted, call `list_columns_customer_db` to retrieve schema +4. Validate that required columns exist: ['customer_id', 'revenue', 'last_purchase_date'] +5. If columns missing, return error: "Required columns not found: [list missing columns]" +6. If columns exist, call `query_sales_data` with filters: + - WHERE last_purchase_date >= DATE_SUB(CURRENT_DATE, INTERVAL 365 DAY) + - AND revenue > 0 +7. Return result set in JSON format +``` + +❌ **Bad - Vague Instructions:** +```markdown +### Task 1: Query Customer Data + +Query the customer database and get the data we need. +``` + +#### 3. Specify Sequential vs. Parallel Execution + +```markdown +**Steps** [sequential=true]: +# Tasks must execute in order - each depends on previous + +**Steps** [parallel=true]: +# Tasks can execute simultaneously - no dependencies +``` + +#### 4. Include Sample Output Formats + +```markdown +**Output Format**: +\```json +{ + "status": "success", + "segments": [ + { + "segment_name": "Champions", + "customer_count": 1250, + "avg_revenue": 5200.00, + "characteristics": { + "recency_score": 5, + "frequency_score": 5, + "monetary_score": 5 + } + } + ], + "total_customers_analyzed": 5000, + "execution_time_ms": 2341 +} +\``` +``` + +--- + +## Section 9: Tools + +Document each tool/function specification. + +### Template + +```markdown +## Tools + +### Tool: `tool_name_in_snake_case` + +| Item | Details | +|------|---------| +| **Function Name** | `tool_name_in_snake_case` | +| **Function Description** | [Brief description of what this function does] | +| **Target** | Knowledge Base / Agent / External API | +| **Target Function** | List Columns / Query Data / Search Schema / Custom | + +#### Input Format +\```json +{ + "parameter1": "value1", + "parameter2": "value2" +} +\``` + +#### Output Format +\```json +{ + "result": "data", + "status": "success" +} +\``` + +#### Example Usage +\``` +User: "Get customer segments" +Tool Call: query_customer_segments({"min_revenue": 1000}) +Tool Response: {"segments": [...], "total": 5} +\``` + +### Tool: `next_tool_name` + +[Follow same structure for each tool] +``` + +### Tool Target Types + +**Knowledge Base Tools:** +- **List Columns**: Retrieve schema information +- **Query Data (Trino SQL)**: Execute SQL queries +- **Search Schema**: Find tables/columns (avoid if possible - can be slow) + +**Agent Tools:** +- **Sub-Agent Call**: Invoke another agent and return results +- **Custom Function**: Execute custom Python/JavaScript code + +### Best Practices for Tool Documentation +1. **Match names** between system prompt and tool specification exactly +2. **Use snake_case** consistently +3. **Provide examples** of inputs and outputs +4. **Document errors** and how the tool handles them +5. **Specify data types** for all parameters + +--- + +## Section 10: Input/Output Format + +Define how users interact with the agent and what they receive. + +### Template + +```markdown +## Input/Output Format + +### Input Format + +**Language Request**: [Natural language or structured format] + +**Sample Dialogue**: +\``` +User: "[Example user query]" +Agent: "[Agent's clarifying question if needed]" +User: "[User's response]" +\``` + +**Optional Parameters**: +- `parameter_name`: [Description, constraints, default value] +- `another_parameter`: [Description, constraints, default value] + +### Output Format + +**Output Type**: HTML / Plotly Graph / Markdown / JSON / Summarized Text + +**Sample Output**: +[Show representative example of what the user receives] + +### Sample Conversation Flow + +\``` +User: "Analyze my customer segments for Q4 2024" + +Agent: "I'll analyze your customer segments. I can use RFM analysis, behavioral clustering, or both. Which would you prefer?" + +User: "Both" + +Agent: [Executes analysis] + +Agent Output: +# Customer Segmentation Analysis - Q4 2024 + +## RFM Segments +[Table showing segments] + +## Behavioral Clusters +[Visualization showing clusters] + +## Key Insights +- [Insight 1] +- [Insight 2] +\``` +``` + +### Output Format Options + +| Format | Best For | Example | +|--------|----------|---------| +| **HTML** | Structured presentation with formatting | Reports, dashboards, formatted tables | +| **Plotly Graph** | Data visualizations | Charts, graphs, interactive visualizations | +| **Markdown** | Text-heavy content with structure | Analysis summaries, documentation | +| **JSON** | Programmatic consumption | API responses, data pipelines | +| **Summarized Text** | Quick insights | Executive summaries, key findings | + +--- + +## Section 11: User Prompts + +User prompts guide the conversation and capture necessary information. + +### Template + +```markdown +## User Prompt: [Prompt Name] + +| Item | Details | +|------|---------| +| **User Prompt Name** | [Descriptive name indicating purpose] | +| **Purpose** | [What this prompt accomplishes] | + +### User Prompt Text + +\``` +Step 1: [First question or instruction] +- Option A: [Description] +- Option B: [Description] +- Option C: [Description] + +Step 2: [Next question based on previous answer] +[Continue step-by-step flow] + +Step 3: [Final configuration] +[Gather remaining details] +\``` + +### Advanced Settings + +**Pre-Configuration Checklist**: +- [ ] [Configuration item 1] +- [ ] [Configuration item 2] +- [ ] [Configuration item 3] + +**System Prompt Override** (if applicable): +[Explain if/when system prompt can be customized by users] + +### Sample Conversation + +\``` +Agent: "Welcome! I can help you with customer segmentation. What would you like to do? +1. Analyze existing segments +2. Create new segments +3. Compare segment performance" + +User: "Analyze existing segments" + +Agent: "Great! Which time period should I analyze? +- Last 30 days +- Last quarter +- Last year +- Custom date range" + +User: "Last quarter" + +Agent: "Analyzing your customer segments for Q3 2024..." +[Proceeds with analysis] +\``` +``` + +### User Prompt Best Practices + +1. **Step-by-step flow**: Guide users through complex tasks incrementally +2. **Clear options**: Provide specific choices rather than open-ended questions +3. **Context**: Explain what each option does and why they'd choose it +4. **Validation**: Include checks to ensure user input is valid +5. **Defaults**: Suggest sensible defaults for common use cases + +--- + +## Section 12: Development Roadmap + +Track the agent's development milestones and future plans. + +### Template + +```markdown +## Development Roadmap + +### Milestones + +| Phase | Date | Deliverables | Status | +|-------|------|--------------|--------| +| **Planning** | [Date] | Requirements, architecture design, team formation | ✅ Complete | +| **Development** | [Date] | Core functionality, tools, system prompt | ✅ Complete | +| **Testing** | [Date] | Unit tests, integration tests, user testing | ✅ Complete | +| **Deployment** | [Date] | Production deployment, documentation, training | 🔄 In Progress | +| **Enhancement** | [Date] | Feature additions, optimizations, feedback integration | 📅 Planned | + +### Future Enhancements +- [ ] [Planned feature 1] +- [ ] [Planned feature 2] +- [ ] [Planned feature 3] +``` + +--- + +## Section 13: Demo + +Provide examples and demonstrations of the agent in action. + +### Template + +```markdown +## Demo + +### Input Example + +\``` +User Query: "[Realistic example user input]" + +Context: +- [Relevant context or prerequisites] +\``` + +### Output Example + +\``` +[Show exactly what the agent returns] + +[Include visualizations, formatted output, or screenshots] +\``` + +### Video Recording + +**Demo Video**: [Link to recording] +**Duration**: [Length] +**Covers**: [What the demo shows] + +### Live Demo Access + +**Demo Environment**: [Link if available] +**Test Credentials**: [If applicable] +**Sample Data**: [Link to sample data for testing] +``` + +--- + +## Complete Documentation Example + +Here's a concise example applying all the templates: + +```markdown +# Customer RFM Segmentation Agent + +## Basic Information + +| Item | Details | +|------|---------| +| **Project Name** | Customer RFM Segmentation Agent | +| **Type** | Field Agent | +| **Interface Type** | Chat | +| **Status** | Production | +| **Version** | 1.2.0 | +| **Model** | Claude 4 Sonnet | +| **Temperature** | 0 | + +## Purpose & Functionality + +### Description +Automatically segments customers using RFM (Recency, Frequency, Monetary) analysis to identify high-value segments and at-risk customers. + +### Business Value +Enables 10x faster customer segmentation, improving campaign targeting by 35% and increasing marketing ROI. + +## System Prompt: RFM Agent + +# Customer RFM Segmentation Agent + +Analyzes customer transaction data to create actionable segments. + +# Role +- Query customer transaction databases +- Calculate RFM scores for each customer +- Assign customers to segments based on scores +- Generate visualizations and insights + +# Goal +Provide marketers with clear customer segments and actionable insights for targeted campaigns. + +## Available Tools + +### Database Access +**Tool**: `verify_database_access` +**Purpose**: Verify user has access to customer database +**Input**: Database name +**Output**: Access status (granted/denied) + +### Data Retrieval +**Tool**: `query_customer_transactions` +**Purpose**: Retrieve customer transaction history +**Input**: Database, table, date range +**Output**: Transaction records with customer_id, date, amount + +### RFM Calculation +**Tool**: `calculate_rfm_scores` +**Purpose**: Calculate Recency, Frequency, Monetary scores +**Input**: Transaction data +**Output**: RFM scores per customer + +### Visualization +**Tool**: `generate_segment_chart` +**Purpose**: Create Plotly visualization of segments +**Input**: Segment data +**Output**: Plotly JSON chart specification + +## Task Flow + +### Task 1: Verify Access [required = true, mandatory_start = true] + +**Steps** [sequential=true]: +1. Call `verify_database_access` with customer database name +2. If access denied, return error and stop +3. If access granted, proceed to Task 2 + +### Task 2: Retrieve Transaction Data [required = true] + +**Steps** [sequential=true]: +1. Call `query_customer_transactions` with date range (default: last 365 days) +2. Validate minimum 100 records returned +3. If insufficient data, warn user and ask to expand date range +4. Proceed to Task 3 + +### Task 3: Calculate RFM [required = true] + +**Steps** [sequential=true]: +1. Call `calculate_rfm_scores` with transaction data +2. Assign scores 1-5 for Recency (days since last purchase) +3. Assign scores 1-5 for Frequency (number of purchases) +4. Assign scores 1-5 for Monetary (total revenue) +5. Create segments based on score combinations: + - Champions: RFM 5-5-5 + - Loyal: RFM 4-5-4 or 5-4-5 + - At Risk: RFM 2-3-3 or 3-2-3 + - Lost: RFM 1-1-1 +6. Proceed to Task 4 + +### Task 4: Generate Output [required = true] + +**Steps** [parallel=true]: +1. Call `generate_segment_chart` to create visualization +2. Format summary statistics +3. Compile key insights + +**Output Format**: +\```json +{ + "segments": [ + {"name": "Champions", "count": 1250, "avg_revenue": 5200}, + {"name": "Loyal", "count": 2100, "avg_revenue": 3100} + ], + "chart": { "plotly_json": "..." }, + "insights": ["45% of revenue from Champions (25% of customers)"] +} +\``` +``` + +--- + +## Best Practices Summary + +### Documentation Do's ✅ +- Use clear, descriptive tool names in snake_case +- Provide detailed pseudo-logic in system prompts +- Include sample inputs and outputs for every tool +- Keep documentation updated with code changes +- Use semantic versioning +- Include visual examples and demos +- Document error handling explicitly + +### Documentation Don'ts ❌ +- Don't use vague tool names (verify, list, query) +- Don't write generic system prompts without details +- Don't skip example conversations +- Don't forget to update version numbers +- Don't leave links broken or outdated +- Don't omit dependencies or prerequisites +- Don't publish without demo/video + +--- + +## Quick Reference: Tool Naming + +| Purpose | Good Name | Bad Name | +|---------|-----------|----------| +| Verify database access | `verify_database_access` | `verify` | +| List columns from customer DB | `list_columns_customer_db` | `listColumns` | +| Query sales data | `query_sales_data` | `query` | +| Calculate RFM scores | `calculate_rfm_scores` | `calcRFM` | +| Generate visualization | `generate_segment_chart` | `makeChart` | + +--- + +By following this comprehensive documentation template, your Field Agent documentation will be clear, consistent, and professional, making it easy for users to understand, deploy, and use your agents effectively. diff --git a/skills/visualization/SKILL.md b/skills/visualization/SKILL.md new file mode 100644 index 0000000..1fcf5de --- /dev/null +++ b/skills/visualization/SKILL.md @@ -0,0 +1,975 @@ +--- +name: field-agent-visualization +description: Professional Plotly visualization best practices for Field Agents including chart specifications, color palettes, formatting standards, and JSON structure requirements for executive-ready data visualizations +--- + +# Field Agent Visualization Best Practices + +This skill provides comprehensive guidelines for creating professional, executive-ready visualizations for Field Agents using Plotly. Follow these standards to ensure clean, readable, and impactful data visualizations. + +## When to Use This Skill + +Use this skill when you need to: +- Create Plotly visualizations for Field Agent outputs +- Generate charts for data analysis and reporting +- Build dashboards with KPI indicators +- Design executive-ready visual presentations +- Ensure consistent visualization standards across agents + +## Core Principles + +### Golden Rules +1. **Create SINGLE CHARTS ONLY** - NO SUBPLOTS for analysis charts +2. **Always use descriptive titles, axis labels, and legends** +3. **Ensure proper formatting and readability** +4. **Use the specified color palette consistently** +5. **Always show numbers/percentages in bar charts and heatmaps** +6. **LEGENDS MUST BE VISIBLE** for pie charts and comparison charts +7. **NEVER CREATE SUBPLOTS** for analysis - Always create separate individual charts + +## MANDATORY Color Palette + +Always use this Treasure Data color palette for consistency: + +```python +TD_COLORS = [ + '#44BAB8', # Teal (Primary) + '#8FD6D4', # Light Teal + '#DAF1F1', # Pale Teal + '#2E41A6', # Navy Blue + '#828DCA', # Purple + '#D5D9ED', # Light Purple + '#8CC97E', # Green + '#BADFB2', # Light Green + '#E8F4E5', # Pale Green + '#EEB53A', # Accent Yellow + '#F5D389', # Light Yellow + '#5FCFD8', # Cyan + '#A05EB0', # Magenta + '#C69ED0' # Light Magenta +] +``` + +**Usage:** +- Use `#44BAB8` (Teal) as primary color for single-series charts +- Use `#2E41A6` (Navy) for text and titles +- Cycle through colors for multi-series charts +- Use color scales for heatmaps (DAF1F1 → 8FD6D4 → 44BAB8) + +### Color Conversion Helper Function + +For charts requiring RGB/RGBA format (e.g., transparency effects): + +```python +def hex_to_rgb(hex_color): + """Convert hex color to RGB tuple + + Args: + hex_color (str): Hex color code (e.g., '#44BAB8' or '44BAB8') + + Returns: + tuple: RGB values as (R, G, B) where each value is 0-255 + + Example: + >>> hex_to_rgb('#44BAB8') + (68, 186, 184) + """ + hex_color = hex_color.lstrip('#') + return tuple(int(hex_color[i:i+2], 16) for i in (0, 2, 4)) + +def hex_to_rgba(hex_color, alpha=1.0): + """Convert hex color to RGBA string for Plotly + + Args: + hex_color (str): Hex color code (e.g., '#44BAB8') + alpha (float): Opacity value 0.0-1.0 + + Returns: + str: RGBA color string (e.g., 'rgba(68, 186, 184, 0.5)') + + Example: + >>> hex_to_rgba('#44BAB8', 0.5) + 'rgba(68, 186, 184, 0.5)' + """ + r, g, b = hex_to_rgb(hex_color) + return f'rgba({r}, {g}, {b}, {alpha})' + +# Usage examples: +td_primary_rgb = hex_to_rgb('#44BAB8') # (68, 186, 184) +td_primary_transparent = hex_to_rgba('#44BAB8', 0.3) # 'rgba(68, 186, 184, 0.3)' +``` + +--- + +## CRITICAL: JSON Structure Requirements + +### ✅ CORRECT JSON Format + +Always use proper JSON objects with native arrays and objects: + +```json +{ + "data": [ + { + "type": "bar", + "x": ["A", "B", "C"], + "y": [10, 20, 30], + "marker": {"color": "#44BAB8"}, + "text": ["10", "20", "30"], + "textposition": "outside", + "textfont": {"size": 11, "color": "black"} + } + ], + "layout": { + "title": { + "text": "Chart Title", + "x": 0.5, + "font": {"size": 18, "color": "#2E41A6"} + }, + "height": 500, + "showlegend": true, + "margin": {"t": 120, "b": 80, "l": 80, "r": 80}, + "font": {"family": "Arial", "size": 12}, + "plot_bgcolor": "white", + "paper_bgcolor": "white" + } +} +``` + +### ❌ NEVER DO: String Data (Causes Errors) + +```json +{ + "data": "[{\"type\": \"bar\", \"x\": [\"A\", \"B\"], \"y\": [10, 20]}]" +} +``` + +**Critical**: Data must be JSON objects and arrays, NOT stringified JSON. + +--- + +## CRITICAL: Missing Elements Fixes + +### For Bar Charts - MANDATORY Properties + +```json +{ + "data": [{ + "type": "bar", + "x": ["Category A", "Category B", "Category C"], + "y": [45, 30, 25], + "name": "Series Name", + "marker": {"color": "#44BAB8"}, + "text": [45, 30, 25], // ⚠️ CRITICAL: Must include for numbers on bars + "textposition": "outside", // ⚠️ CRITICAL: Shows numbers above bars + "textfont": {"size": 11, "color": "black"} + }], + "layout": { + "title": {"text": "Bar Chart Title", "x": 0.5, "font": {"size": 18}}, + "height": 500, + "showlegend": true, // ⚠️ CRITICAL: Must be true for multi-series + "legend": { + "orientation": "h", + "yanchor": "bottom", + "y": 1.05, // ⚠️ CRITICAL: Must be above 1.0 to be visible + "xanchor": "center", + "x": 0.5 + }, + "margin": {"t": 120, "b": 80, "l": 80, "r": 80}, // ⚠️ CRITICAL: Extra top margin for legend + "xaxis": {"title": {"text": "Categories", "font": {"size": 14}}}, + "yaxis": {"title": {"text": "Values", "font": {"size": 14}}}, + "font": {"family": "Arial", "size": 12}, + "plot_bgcolor": "white", + "paper_bgcolor": "white" + } +} +``` + +### For Heatmaps - MANDATORY Properties + +```json +{ + "data": [{ + "type": "heatmap", + "x": ["Col A", "Col B", "Col C"], + "y": ["Row 1", "Row 2", "Row 3"], + "z": [[23.4, 45.6, 12.3], [34.5, 56.7, 23.1], [45.2, 67.8, 34.5]], + "text": [[23.4, 45.6, 12.3], [34.5, 56.7, 23.1], [45.2, 67.8, 34.5]], // ⚠️ CRITICAL: Numbers to display + "texttemplate": "%{text:.1f}", // ⚠️ CRITICAL: Format to 1 decimal + "textfont": {"size": 12, "color": "black"}, // ⚠️ CRITICAL: Visible text + "showscale": true, // ⚠️ CRITICAL: Show color scale + "colorscale": [ + [0, "#DAF1F1"], + [0.5, "#8FD6D4"], + [1, "#44BAB8"] + ], + "colorbar": { + "title": {"text": "Value", "font": {"size": 12}}, + "titleside": "right" + }, + "hovertemplate": "%{y} - %{x}
Value: %{z:.1f}" + }], + "layout": { + "title": {"text": "Heatmap Title", "x": 0.5, "font": {"size": 18}}, + "height": 500, + "xaxis": {"title": {"text": "X Axis", "font": {"size": 14}}}, + "yaxis": {"title": {"text": "Y Axis", "font": {"size": 14}}}, + "margin": {"t": 80, "b": 80, "l": 80, "r": 100}, + "font": {"family": "Arial", "size": 12}, + "plot_bgcolor": "white", + "paper_bgcolor": "white" + } +} +``` + +### Common Issues Fix Checklist + +Before generating any chart, verify: + +- [ ] **Bar charts**: Include `"text"`, `"textposition": "outside"`, `"textfont"` +- [ ] **Multi-series**: Include `"showlegend": true`, legend `"y": 1.05` or higher +- [ ] **Legend spacing**: Top margin `"t": 120` minimum for horizontal legends +- [ ] **Heatmaps**: Include `"text"`, `"texttemplate": "%{text:.1f}"`, `"showscale": true` +- [ ] **Text visibility**: Use `"textfont": {"color": "black"}` for contrast +- [ ] **JSON format**: Use proper objects/arrays, NOT stringified JSON +- [ ] **Color palette**: Use TD colors exclusively +- [ ] **No subplots**: Create individual charts for analysis + +--- + +## Chart-Specific Guidelines + +### 1. Pie Charts - LEGEND MANDATORY + +Pie charts **ALWAYS** require visible legends. + +```json +{ + "data": [{ + "type": "pie", + "values": [45, 30, 25], + "labels": ["Channel A", "Channel B", "Channel C"], + "marker": { + "colors": ["#44BAB8", "#8FD6D4", "#DAF1F1"] + }, + "textinfo": "label+percent", + "textposition": "auto", + "textfont": {"size": 14, "color": "black"}, + "hovertemplate": "%{label}
Value: %{value}
Percentage: %{percent}" + }], + "layout": { + "title": { + "text": "Attribution Distribution", + "x": 0.5, + "font": {"size": 18, "color": "#2E41A6"} + }, + "height": 500, + "showlegend": true, + "legend": { + "orientation": "v", + "yanchor": "middle", + "y": 0.5, + "xanchor": "left", + "x": 1.02, + "font": {"size": 12} + }, + "margin": {"t": 80, "b": 80, "l": 80, "r": 150}, + "font": {"family": "Arial", "size": 12}, + "paper_bgcolor": "white" + } +} +``` + +**Key Points:** +- Use vertical legend positioned to the right (`x: 1.02`) +- Include extra right margin (`r: 150`) for legend space +- Show both label and percent in slices +- Use TD color palette for consistent branding + +--- + +### 2. Bar Charts with Comparison - LEGEND VISIBLE + +Multi-series bar charts require horizontal legends positioned above the chart. + +```json +{ + "data": [ + { + "type": "bar", + "x": ["Channel A", "Channel B", "Channel C"], + "y": [45, 30, 25], + "name": "Metric 1", + "marker": {"color": "#44BAB8"}, + "text": [45, 30, 25], + "textposition": "outside", + "textfont": {"size": 11, "color": "black"} + }, + { + "type": "bar", + "x": ["Channel A", "Channel B", "Channel C"], + "y": [35, 40, 30], + "name": "Metric 2", + "marker": {"color": "#8FD6D4"}, + "text": [35, 40, 30], + "textposition": "outside", + "textfont": {"size": 11, "color": "black"} + } + ], + "layout": { + "title": { + "text": "Channel Comparison", + "x": 0.5, + "font": {"size": 18, "color": "#2E41A6"} + }, + "height": 500, + "barmode": "group", + "showlegend": true, + "legend": { + "orientation": "h", + "yanchor": "bottom", + "y": 1.05, + "xanchor": "center", + "x": 0.5, + "font": {"size": 12} + }, + "xaxis": { + "title": {"text": "Channels", "font": {"size": 14, "color": "#2E41A6"}} + }, + "yaxis": { + "title": {"text": "Performance %", "font": {"size": 14, "color": "#2E41A6"}} + }, + "margin": {"t": 120, "b": 80, "l": 80, "r": 80}, + "font": {"family": "Arial", "size": 12}, + "plot_bgcolor": "white", + "paper_bgcolor": "white" + } +} +``` + +**Key Points:** +- Set `barmode` to `"group"` for side-by-side or `"stack"` for stacked +- Horizontal legend above chart (`y: 1.05`) +- Adequate top margin (`t: 120`) +- Numbers displayed on all bars + +--- + +### 3. Single Bar Chart - NO Legend Needed + +```json +{ + "data": [{ + "type": "bar", + "x": ["Product A", "Product B", "Product C", "Product D"], + "y": [1200, 950, 800, 650], + "marker": {"color": "#44BAB8"}, + "text": ["$1,200", "$950", "$800", "$650"], + "textposition": "outside", + "textfont": {"size": 11, "color": "black"} + }], + "layout": { + "title": { + "text": "Revenue by Product", + "x": 0.5, + "font": {"size": 18, "color": "#2E41A6"} + }, + "height": 500, + "showlegend": false, + "xaxis": { + "title": {"text": "Products", "font": {"size": 14, "color": "#2E41A6"}} + }, + "yaxis": { + "title": {"text": "Revenue ($)", "font": {"size": 14, "color": "#2E41A6"}} + }, + "margin": {"t": 80, "b": 80, "l": 80, "r": 80}, + "font": {"family": "Arial", "size": 12}, + "plot_bgcolor": "white", + "paper_bgcolor": "white" + } +} +``` + +**Key Points:** +- Single series = no legend needed (`showlegend: false`) +- Use primary TD color (#44BAB8) +- Show formatted values on bars + +--- + +### 4. Heatmaps - Numbers with 1 Decimal + +```json +{ + "data": [{ + "type": "heatmap", + "x": ["Channel A", "Channel B", "Channel C"], + "y": ["Week 1", "Week 2", "Week 3"], + "z": [ + [23.4, 45.6, 12.3], + [34.5, 56.7, 23.1], + [45.2, 67.8, 34.5] + ], + "colorscale": [ + [0, "#DAF1F1"], + [0.5, "#8FD6D4"], + [1, "#44BAB8"] + ], + "showscale": true, + "colorbar": { + "title": {"text": "Performance", "font": {"size": 12}}, + "titleside": "right" + }, + "text": [ + [23.4, 45.6, 12.3], + [34.5, 56.7, 23.1], + [45.2, 67.8, 34.5] + ], + "texttemplate": "%{text:.1f}", + "textfont": {"size": 12, "color": "black"}, + "hovertemplate": "%{y} - %{x}
Value: %{z:.1f}" + }], + "layout": { + "title": { + "text": "Performance Heatmap", + "x": 0.5, + "font": {"size": 18, "color": "#2E41A6"} + }, + "height": 500, + "xaxis": { + "title": {"text": "Channels", "font": {"size": 14, "color": "#2E41A6"}} + }, + "yaxis": { + "title": {"text": "Time Periods", "font": {"size": 14, "color": "#2E41A6"}} + }, + "margin": {"t": 80, "b": 80, "l": 80, "r": 100}, + "font": {"family": "Arial", "size": 12}, + "plot_bgcolor": "white", + "paper_bgcolor": "white" + } +} +``` + +**Key Points:** +- Include `text` array matching `z` values +- Use `texttemplate: "%{text:.1f}"` for 1 decimal formatting +- Use TD color scale (light to dark) +- Show color scale bar + +--- + +### 5. Line Charts with Multiple Series + +```json +{ + "data": [ + { + "type": "scatter", + "mode": "lines+markers", + "x": ["Jan", "Feb", "Mar", "Apr"], + "y": [10, 15, 20, 25], + "name": "Channel A", + "line": {"color": "#44BAB8", "width": 3}, + "marker": {"color": "#44BAB8", "size": 8} + }, + { + "type": "scatter", + "mode": "lines+markers", + "x": ["Jan", "Feb", "Mar", "Apr"], + "y": [8, 12, 18, 22], + "name": "Channel B", + "line": {"color": "#8FD6D4", "width": 3}, + "marker": {"color": "#8FD6D4", "size": 8} + } + ], + "layout": { + "title": { + "text": "Performance Trends", + "x": 0.5, + "font": {"size": 18, "color": "#2E41A6"} + }, + "height": 500, + "showlegend": true, + "legend": { + "orientation": "h", + "yanchor": "bottom", + "y": 1.02, + "xanchor": "center", + "x": 0.5, + "font": {"size": 12} + }, + "xaxis": { + "title": {"text": "Time Period", "font": {"size": 14, "color": "#2E41A6"}} + }, + "yaxis": { + "title": {"text": "Performance", "font": {"size": 14, "color": "#2E41A6"}} + }, + "margin": {"t": 100, "b": 80, "l": 80, "r": 80}, + "font": {"family": "Arial", "size": 12}, + "plot_bgcolor": "white", + "paper_bgcolor": "white" + } +} +``` + +**Key Points:** +- Use `scatter` type with `mode: "lines+markers"` +- Different colors for each series from TD palette +- Horizontal legend above chart +- Visible markers on data points + +--- + +### 6. Sankey Diagrams + +```json +{ + "data": [{ + "type": "sankey", + "orientation": "h", + "node": { + "pad": 15, + "thickness": 30, + "line": {"color": "black", "width": 0.5}, + "label": ["Source A", "Source B", "Destination X", "Destination Y"], + "color": ["#44BAB8", "#8FD6D4", "#2E41A6", "#828DCA"] + }, + "link": { + "source": [0, 1, 0, 1], + "target": [2, 2, 3, 3], + "value": [10, 20, 15, 25], + "color": [ + "rgba(68, 186, 184, 0.4)", + "rgba(143, 214, 212, 0.4)", + "rgba(68, 186, 184, 0.4)", + "rgba(143, 214, 212, 0.4)" + ] + } + }], + "layout": { + "title": { + "text": "Customer Journey Flow", + "x": 0.5, + "font": {"size": 18, "color": "#2E41A6"} + }, + "height": 600, + "margin": {"t": 80, "b": 50, "l": 50, "r": 50}, + "font": {"family": "Arial", "size": 12}, + "paper_bgcolor": "white" + } +} +``` + +**Key Points:** +- Node colors from TD palette +- Semi-transparent link colors (0.4 opacity) +- Clear node labels +- Adequate height (600px) for visibility + +--- + +## Legend Configuration Standards + +### When to Show Legends + +| Chart Type | Show Legend? | Position | +|------------|--------------|----------| +| **Pie Chart** | ✅ ALWAYS | Vertical, right side | +| **Multi-Series Bar** | ✅ ALWAYS | Horizontal, top | +| **Single Bar** | ❌ NEVER | N/A | +| **Multi-Series Line** | ✅ ALWAYS | Horizontal, top | +| **Single Line** | ❌ NEVER | N/A | +| **Heatmap** | ❌ (Use colorbar) | N/A | +| **Sankey** | ❌ (Labels in nodes) | N/A | + +### Pie Charts - Vertical Legend (Right Side) + +```json +{ + "showlegend": true, + "legend": { + "orientation": "v", + "yanchor": "middle", + "y": 0.5, + "xanchor": "left", + "x": 1.02, + "font": {"size": 12} + }, + "margin": {"t": 80, "b": 80, "l": 80, "r": 150} +} +``` + +### Bar/Line Charts - Horizontal Legend (Top) + +```json +{ + "showlegend": true, + "legend": { + "orientation": "h", + "yanchor": "bottom", + "y": 1.05, + "xanchor": "center", + "x": 0.5, + "font": {"size": 12} + }, + "margin": {"t": 120, "b": 80, "l": 80, "r": 80} +} +``` + +--- + +## Text and Number Formatting + +### Percentage Display + +```json +// Option 1: Add % in template +{ + "text": [45.2, 30.1, 24.7], + "texttemplate": "%{text}%", + "textposition": "outside", + "textfont": {"size": 11, "color": "black"} +} + +// Option 2: Pre-formatted strings +{ + "text": ["45.2%", "30.1%", "24.7%"], + "textposition": "outside", + "textfont": {"size": 11, "color": "black"} +} +``` + +### Currency Display + +```json +// Option 1: Format with template +{ + "text": [1200000, 850000, 650000], + "texttemplate": "$%{text:,.0f}", + "textposition": "outside", + "textfont": {"size": 11, "color": "black"} +} + +// Option 2: Pre-formatted strings +{ + "text": ["$1.2M", "$850K", "$650K"], + "textposition": "outside", + "textfont": {"size": 11, "color": "black"} +} +``` + +### Heatmap Numbers (1 Decimal) + +```json +{ + "text": [[23.4, 45.6], [34.5, 56.7]], + "texttemplate": "%{text:.1f}", + "textfont": {"size": 12, "color": "black"}, + "hovertemplate": "Value: %{z:.1f}" +} +``` + +--- + +## KPI Indicators (ONLY Use Case for Subplots) + +KPI indicators are the **ONLY** exception where subplots are allowed. Use simple number indicators only. + +### Simple Number Indicators (NO GAUGES) + +```json +{ + "data": [ + { + "type": "indicator", + "mode": "number+delta", + "value": 5240, + "delta": {"reference": 4800, "suffix": " customers"}, + "title": {"text": "Total Customers", "font": {"size": 12, "color": "#2E41A6"}}, + "number": {"font": {"size": 32, "color": "#44BAB8"}}, + "domain": {"x": [0, 0.25], "y": [0, 1]} + }, + { + "type": "indicator", + "mode": "number+delta", + "value": 42.5, + "delta": {"reference": 38.2, "suffix": "%"}, + "title": {"text": "Conversion Rate", "font": {"size": 12, "color": "#2E41A6"}}, + "number": {"prefix": "", "suffix": "%", "font": {"size": 32, "color": "#44BAB8"}}, + "domain": {"x": [0.25, 0.5], "y": [0, 1]} + }, + { + "type": "indicator", + "mode": "number+delta", + "value": 1250000, + "delta": {"reference": 1100000, "valueformat": "$,.0f"}, + "title": {"text": "Total Revenue", "font": {"size": 12, "color": "#2E41A6"}}, + "number": {"prefix": "$", "valueformat": ",.0f", "font": {"size": 32, "color": "#44BAB8"}}, + "domain": {"x": [0.5, 0.75], "y": [0, 1]} + }, + { + "type": "indicator", + "mode": "number+delta", + "value": 25.3, + "delta": {"reference": 22.1, "suffix": "%"}, + "title": {"text": "Champions %", "font": {"size": 12, "color": "#2E41A6"}}, + "number": {"suffix": "%", "font": {"size": 32, "color": "#44BAB8"}}, + "domain": {"x": [0.75, 1], "y": [0, 1]} + } + ], + "layout": { + "height": 150, + "margin": {"t": 20, "b": 20, "l": 20, "r": 20}, + "paper_bgcolor": "white" + } +} +``` + +**Key Points for KPI Indicators:** +- Maximum 4 indicators per row +- **Number + Delta ONLY** - no gauges, no fancy visuals +- Large number (32pt), clear title (12pt) +- Show change vs. previous period +- Clean, minimal design +- Use domains to position: `[0, 0.25]`, `[0.25, 0.5]`, `[0.5, 0.75]`, `[0.75, 1]` + +--- + +## Quality Checklist + +Before generating any visualization, verify: + +### Required for Every Chart +- [ ] Descriptive title with proper positioning (`"x": 0.5`) +- [ ] Clear axis labels with appropriate font size (`"font": {"size": 14}`) +- [ ] TD color palette used consistently +- [ ] Proper height (500-600px based on chart type) +- [ ] Adequate margins (minimum 80px, more for legends) +- [ ] White background (`"plot_bgcolor": "white", "paper_bgcolor": "white"`) +- [ ] Readable font size (12px minimum) +- [ ] Legends visible for multi-category/multi-series charts +- [ ] Numbers displayed on bars/heatmaps with proper formatting + +### Legend Requirements +- [ ] `"showlegend": true` for pie charts and comparisons +- [ ] Proper orientation (vertical for pie, horizontal for others) +- [ ] Adequate margin space for legend display +- [ ] Readable font size for legend items +- [ ] Legend positioned visibly (y > 1.0 for horizontal) + +### Text Display Requirements +- [ ] Values shown on bars with `"text"` and `"textposition"` +- [ ] Heatmap values formatted to 1 decimal place +- [ ] Hover templates with meaningful information +- [ ] Consistent text formatting across similar chart types +- [ ] Black text for visibility (`"textfont": {"color": "black"}`) + +--- + +## Forbidden Patterns + +### ❌ NEVER DO + +1. **Subplots for analysis** (`yaxis2`, `xaxis2`, domain specifications) + - Exception: KPI indicators only +2. **String data format** (`"data": "[...]"`) +3. **Missing legends** on pie charts or comparisons +4. **Legend positioned below visible area** (e.g., `"y": -0.3`) +5. **Missing `"text"` property on bar charts** - numbers won't show +6. **Missing `"textposition"` on bar charts** - numbers won't be positioned +7. **Missing `"texttemplate"` on heatmaps** - numbers won't be formatted +8. **Missing `"showscale"` on heatmaps** - color scale won't appear +9. **Insufficient top margin** for legends (`"t": 80` insufficient, use `"t": 120`) +10. **Unformatted numbers** in heatmaps +11. **Empty or generic titles** +12. **Non-TD colors** +13. **Gauges in KPI indicators** - use number+delta only + +### ✅ ALWAYS DO + +1. **Individual separate charts** for analysis +2. **JSON array data format** (proper objects, not strings) +3. **Visible legends**: `"y": 1.05` for horizontal, adequate margins +4. **Numbers on bars**: `"text": [...]`, `"textposition": "outside"` +5. **Numbers on heatmaps**: `"text": [...]`, `"texttemplate": "%{text:.1f}"` +6. **Adequate margins**: `"t": 120` minimum for legends +7. **Formatted numbers** with appropriate decimals +8. **Descriptive titles** and axis labels +9. **TD color palette** consistently +10. **Black text color** for visibility: `"textfont": {"color": "black"}` +11. **Simple KPI indicators** - number + delta only + +--- + +## Complete Examples + +### Example 1: Customer Segment Distribution (Pie Chart) + +```json +{ + "data": [{ + "type": "pie", + "values": [1250, 2100, 1500, 390], + "labels": ["Champions", "Loyal Customers", "At Risk", "Lost"], + "marker": { + "colors": ["#44BAB8", "#8FD6D4", "#EEB53A", "#828DCA"] + }, + "textinfo": "label+percent", + "textposition": "auto", + "textfont": {"size": 14, "color": "black"}, + "hovertemplate": "%{label}
Customers: %{value}
Percentage: %{percent}" + }], + "layout": { + "title": { + "text": "Customer Segment Distribution", + "x": 0.5, + "font": {"size": 18, "color": "#2E41A6"} + }, + "height": 500, + "showlegend": true, + "legend": { + "orientation": "v", + "yanchor": "middle", + "y": 0.5, + "xanchor": "left", + "x": 1.02, + "font": {"size": 12} + }, + "margin": {"t": 80, "b": 80, "l": 80, "r": 150}, + "font": {"family": "Arial", "size": 12}, + "paper_bgcolor": "white" + } +} +``` + +### Example 2: Revenue by Channel (Multi-Series Bar) + +```json +{ + "data": [ + { + "type": "bar", + "x": ["Email", "Social", "Search", "Display"], + "y": [125000, 98000, 156000, 67000], + "name": "Q3 2024", + "marker": {"color": "#44BAB8"}, + "text": ["$125K", "$98K", "$156K", "$67K"], + "textposition": "outside", + "textfont": {"size": 11, "color": "black"} + }, + { + "type": "bar", + "x": ["Email", "Social", "Search", "Display"], + "y": [142000, 115000, 178000, 73000], + "name": "Q4 2024", + "marker": {"color": "#8FD6D4"}, + "text": ["$142K", "$115K", "$178K", "$73K"], + "textposition": "outside", + "textfont": {"size": 11, "color": "black"} + } + ], + "layout": { + "title": { + "text": "Revenue by Marketing Channel", + "x": 0.5, + "font": {"size": 18, "color": "#2E41A6"} + }, + "height": 500, + "barmode": "group", + "showlegend": true, + "legend": { + "orientation": "h", + "yanchor": "bottom", + "y": 1.05, + "xanchor": "center", + "x": 0.5, + "font": {"size": 12} + }, + "xaxis": { + "title": {"text": "Marketing Channels", "font": {"size": 14, "color": "#2E41A6"}} + }, + "yaxis": { + "title": {"text": "Revenue ($)", "font": {"size": 14, "color": "#2E41A6"}} + }, + "margin": {"t": 120, "b": 80, "l": 80, "r": 80}, + "font": {"family": "Arial", "size": 12}, + "plot_bgcolor": "white", + "paper_bgcolor": "white" + } +} +``` + +### Example 3: Performance Heatmap + +```json +{ + "data": [{ + "type": "heatmap", + "x": ["Week 1", "Week 2", "Week 3", "Week 4"], + "y": ["Email", "Social", "Search", "Display"], + "z": [ + [85.3, 92.1, 88.7, 94.2], + [72.5, 78.3, 81.2, 76.8], + [91.4, 89.6, 93.8, 95.1], + [68.2, 71.5, 69.9, 73.4] + ], + "colorscale": [ + [0, "#DAF1F1"], + [0.5, "#8FD6D4"], + [1, "#44BAB8"] + ], + "showscale": true, + "colorbar": { + "title": {"text": "Performance %", "font": {"size": 12}}, + "titleside": "right" + }, + "text": [ + [85.3, 92.1, 88.7, 94.2], + [72.5, 78.3, 81.2, 76.8], + [91.4, 89.6, 93.8, 95.1], + [68.2, 71.5, 69.9, 73.4] + ], + "texttemplate": "%{text:.1f}", + "textfont": {"size": 12, "color": "black"}, + "hovertemplate": "%{y} - %{x}
Performance: %{z:.1f}%" + }], + "layout": { + "title": { + "text": "Weekly Channel Performance", + "x": 0.5, + "font": {"size": 18, "color": "#2E41A6"} + }, + "height": 500, + "xaxis": { + "title": {"text": "Week", "font": {"size": 14, "color": "#2E41A6"}} + }, + "yaxis": { + "title": {"text": "Channel", "font": {"size": 14, "color": "#2E41A6"}} + }, + "margin": {"t": 80, "b": 80, "l": 100, "r": 100}, + "font": {"family": "Arial", "size": 12}, + "plot_bgcolor": "white", + "paper_bgcolor": "white" + } +} +``` + +--- + +## Success Criteria + +Your visualization is ready when: + +✅ Executives can instantly understand the key message +✅ All text is readable at standard screen sizes +✅ Colors are consistent with TD branding +✅ Legends are visible and descriptive (where needed) +✅ Numbers are formatted appropriately +✅ Chart tells a clear story +✅ JSON structure is valid (not stringified) +✅ No subplots for analysis charts +✅ Clean, professional, executive-ready appearance + +--- + +By following these guidelines, your Field Agent visualizations will be professional, consistent, and immediately actionable for decision-makers.