Initial commit
This commit is contained in:
Zhongwei Li
14
.claude-plugin/plugin.json
Normal file
14
.claude-plugin/plugin.json
Normal file
@@ -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"
|
||||||
|
]
|
||||||
|
}
|
||||||
3
README.md
Normal file
3
README.md
Normal file
@@ -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
|
||||||
52
plugin.lock.json
Normal file
52
plugin.lock.json
Normal file
@@ -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": []
|
||||||
|
}
|
||||||
|
}
|
||||||
422
skills/deployment/SKILL.md
Normal file
422
skills/deployment/SKILL.md
Normal file
@@ -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
|
||||||
941
skills/documentation/SKILL.md
Normal file
941
skills/documentation/SKILL.md
Normal file
@@ -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_<tool_name>[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.
|
||||||
975
skills/visualization/SKILL.md
Normal file
975
skills/visualization/SKILL.md
Normal file
@@ -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": "<b>%{y}</b> - <b>%{x}</b><br>Value: %{z:.1f}<extra></extra>"
|
||||||
|
}],
|
||||||
|
"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": "<b>%{label}</b><br>Value: %{value}<br>Percentage: %{percent}<extra></extra>"
|
||||||
|
}],
|
||||||
|
"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": "<b>%{y}</b> - <b>%{x}</b><br>Value: %{z:.1f}<extra></extra>"
|
||||||
|
}],
|
||||||
|
"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}<extra></extra>"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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": "<b>%{label}</b><br>Customers: %{value}<br>Percentage: %{percent}<extra></extra>"
|
||||||
|
}],
|
||||||
|
"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": "<b>%{y}</b> - <b>%{x}</b><br>Performance: %{z:.1f}%<extra></extra>"
|
||||||
|
}],
|
||||||
|
"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.
|
||||||
Reference in New Issue
Block a user