Agent Guidelines for streamlit-lightweight-charts-pro

This document provides specialized guidance for AI agents (autonomous task executors) working on the streamlit-lightweight-charts-pro codebase.

Table of Contents

• Agent Roles
• Task Patterns
• Search Strategies
• Code Modification Patterns
• Testing Strategies
• Error Recovery
• Performance Guidelines

Agent Roles

General Purpose Agent

Use for: Multi-step tasks, research, complex searches, planning

Capabilities:

• Read multiple files in sequence
• Search codebase with multiple strategies
• Execute multi-step workflows
• Create comprehensive plans
• Coordinate between Python and TypeScript

Example Tasks:

• "Investigate how session state persistence works"
• "Find all references to lazy loading and remove them"
• "Research and document the series factory pattern"

Explore Agent

Use for: Quick codebase exploration, finding patterns, understanding architecture

Capabilities:

• Fast file pattern matching
• Keyword searches
• Directory tree exploration
• Quick architecture overview

Example Tasks:

• "Find all files related to chart rendering"
• "Locate series type definitions"
• "Show me the component initialization flow"

Plan Agent

Use for: Designing implementation strategies before coding

Capabilities:

• Architectural analysis
• Trade-off evaluation
• Step-by-step planning
• Critical file identification

Example Tasks:

• "Plan implementation for adding new primitive type"
• "Design approach for optimizing re-render performance"
• "Evaluate strategies for adding lazy loading"

Task Patterns

Pattern 1: Feature Addition

Typical Flow:

1. Plan Agent: Design approach
2. Explore Agent: Find relevant files
3. General Agent: Implement changes
   - Update Python classes
   - Update TypeScript types
   - Add tests
   - Update documentation
4. Verify: Run tests and formatters

Example: Adding new series type

# Step 1: Plan
Plan Agent → "Design implementation for TrendArrow series type"

# Step 2: Explore existing patterns
Explore Agent → "Find all series descriptor files and implementations"

# Step 3: Implement
General Agent →
  - Create TrendArrowSeriesDescriptor.ts
  - Register in descriptors/index.ts
  - Add Python TrendArrowSeries class
  - Add tests
  - Update documentation

# Step 4: Verify
Run: npm run test, pytest tests/, formatters

Pattern 2: Bug Fix

Typical Flow:

1. Explore Agent: Locate bug source
2. General Agent: Understand root cause
3. General Agent: Implement fix
4. General Agent: Add regression test
5. Verify: Ensure fix works

Example: Session state not persisting

# Step 1: Find relevant code
Explore Agent → "Search for session state save/load logic"

# Step 2: Analyze
General Agent → Read session_state_manager.py, chart_renderer.py, chart.py

# Step 3: Fix
General Agent → Update handle_response() to properly save configs

# Step 4: Test
General Agent → Add test_session_state_persistence.py

# Step 5: Verify
Run: pytest tests/test_session_state_persistence.py -v

Pattern 3: Refactoring

Typical Flow:

1. Plan Agent: Design refactoring strategy
2. Explore Agent: Find all affected files
3. General Agent: Execute refactoring
   - Update imports
   - Rename functions/classes
   - Update tests
   - Update documentation
4. Verify: All tests pass

Example: Rename component initialization logic

# Step 1: Plan
Plan Agent → "Design safe refactoring of component initialization"

# Step 2: Find usages
Explore Agent → "Find all files using _initialize_component"

# Step 3: Refactor
General Agent →
  - Rename function
  - Update all call sites
  - Update tests
  - Update comments

# Step 4: Verify
Run: pytest tests/, npm run test, type checks

Pattern 4: Documentation Update

Typical Flow:

1. Explore Agent: Understand current state
2. General Agent: Update documentation
   - Docstrings
   - README
   - CHANGELOG
   - Examples
3. Verify: Documentation builds, examples run

Search Strategies

Finding Functionality

Strategy 1: Start with exports

# Look at __init__.py to find public API
Read: streamlit_lightweight_charts_pro/__init__.py

# Then drill down to implementation
Read: streamlit_lightweight_charts_pro/charts/chart.py

Strategy 2: Search by feature name

Grep: "series_settings" → files_with_matches
Read: Top results to understand implementation

Strategy 3: Follow imports

# Start at entry point
Read: frontend/src/index.tsx

# Follow imports
→ Read: frontend/src/LightweightCharts.tsx
→ Read: frontend/src/series/UnifiedSeriesFactory.ts

Finding Test Files

Pattern:

# Python tests
Glob: tests/**/test_<feature>.py

# TypeScript tests
Glob: frontend/src/__tests__/**/<Component>.test.tsx

Finding Examples

Pattern:

Glob: examples/**/<feature>*.py

Code Modification Patterns

Python Modifications

Always follow this sequence:

# 1. Read the file first
Read: path/to/file.py

# 2. Make changes
Edit: path/to/file.py
  old_string: "..."
  new_string: "..."

# 3. Run formatters (in this exact order)
Bash: isort --float-to-top path/to/file.py
Bash: autoflake --in-place --remove-unused-variables path/to/file.py
Bash: black --line-length 99 --enable-unstable-feature=string_processing --preview path/to/file.py
Bash: ruff check --fix path/to/file.py

# 4. Run tests
Bash: pytest tests/test_specific.py -v

Docstring Template:

def function_name(arg1: Type1, arg2: Type2) -> ReturnType:
    """Short one-line summary.

    Longer description explaining what the function does, why it exists,
    and any important behavioral details.

    Args:
        arg1 (Type1): Description of arg1 with context.
        arg2 (Type2): Description of arg2 with context.

    Returns:
        ReturnType: Description of return value with context.

    Raises:
        ExceptionType: When this exception occurs.

    Example:
        >>> result = function_name(value1, value2)
        >>> print(result)
        expected_output
    """
    # Implementation with inline comments explaining complex logic
    pass

TypeScript Modifications

Always follow this sequence:

// 1. Read the file first
Read: frontend/src/path/to/file.ts

// 2. Make changes
Edit: frontend/src/path/to/file.ts
  old_string: "..."
  new_string: "..."

// 3. Run formatters
Bash: cd frontend && npx prettier --write src/path/to/file.ts
Bash: cd frontend && npx eslint --fix src/path/to/file.ts
Bash: cd frontend && npx tsc --noEmit

// 4. Run tests
Bash: cd frontend && npm run test path/to/file.test.ts

JSDoc Template:

/**
 * Short one-line summary.
 *
 * Longer description explaining what the function does, why it exists,
 * and any important behavioral details.
 *
 * @param arg1 - Description of arg1 with context
 * @param arg2 - Description of arg2 with context
 * @returns Description of return value with context
 *
 * @example
 * ```typescript
 * const result = functionName(value1, value2);
 * console.log(result);
 * ```
 */
export function functionName(arg1: Type1, arg2: Type2): ReturnType {
  // Implementation with inline comments
}

Multi-File Changes

Strategy: Process files in dependency order

# Example: Adding new option

# 1. Core type definition (Python)
Read: lightweight-charts-pro-python/charts/options/chart_options.py
Edit: Add new option field

# 2. Wrapper re-export (Python)
Read: streamlit_lightweight_charts_pro/__init__.py
# Usually no change needed (re-exports from core)

# 3. Frontend type definition (TypeScript)
Read: frontend/src/types.ts
Edit: Add new option to interface

# 4. Frontend usage (TypeScript)
Read: frontend/src/LightweightCharts.tsx
Edit: Use new option in chart creation

# 5. Tests (both)
Edit: tests/test_options.py
Edit: frontend/src/__tests__/components/LightweightCharts.test.tsx

# 6. Examples
Edit: examples/options/new_option_example.py

# 7. Documentation
Edit: README.md
Edit: CHANGELOG.md

Testing Strategies

Test-Driven Development

Recommended approach for new features:

# 1. Write failing test first
Edit: tests/test_new_feature.py

"""Test new feature."""

def test_new_feature():
    # Arrange
    chart = Chart()

    # Act
    result = chart.new_feature()

    # Assert
    assert result is not None
    assert result.property == expected_value

# 2. Run test (should fail)
Bash: pytest tests/test_new_feature.py -v

# 3. Implement feature
Edit: streamlit_lightweight_charts_pro/charts/chart.py

# 4. Run test (should pass)
Bash: pytest tests/test_new_feature.py -v

# 5. Refactor if needed
# 6. Re-run tests to ensure still passing

Test Coverage Gaps

Find untested code:

# Python coverage
Bash: pytest tests/ --cov=streamlit_lightweight_charts_pro --cov-report=html
Read: htmlcov/index.html

# TypeScript coverage
Bash: cd frontend && npm run test:coverage
Read: frontend/coverage/index.html

Visual Regression Tests

When to update snapshots:

// After intentional visual changes
Bash: cd frontend && npm run test:update-snapshots

// Always review changes before committing
Bash: git diff frontend/src/__tests__/**/*-snapshots/

Error Recovery

Common Error Patterns

Error: "Component not available"

Diagnosis:

# Check frontend build
Bash: ls -la streamlit_lightweight_charts_pro/frontend/build/

# If missing, build it
Bash: cd streamlit_lightweight_charts_pro/frontend && npm run build

Error: "Module not found"

Python:

# Check imports are absolute
Read: <file_with_error>
# Verify import paths start with package name

# Reinstall in editable mode
Bash: pip install -e .

TypeScript:

# Check tsconfig paths
Read: frontend/tsconfig.json

# Clear cache and reinstall
Bash: cd frontend && rm -rf node_modules/.vite && npm install

Error: Type checking failures

TypeScript:

# Run type checker
Bash: cd frontend && npx tsc --noEmit

# Fix issues one by one
# Common fixes:
# - Add missing type imports
# - Fix any usage
# - Add type guards
# - Update interface definitions

Error: Test failures

Strategy:

# Run with verbose output
Bash: pytest tests/ -vv --tb=long  # Python
Bash: cd frontend && npm run test -- --reporter=verbose  # TypeScript

# Run specific test
Bash: pytest tests/test_file.py::test_function -vv

# Use debugger
Bash: pytest tests/ --pdb  # Python
Bash: cd frontend && npm run test:ui  # TypeScript (interactive)

Recovery Procedures

Corrupted Session State

# Clear session state in app
import streamlit as st

if st.button("Clear Session State"):
    st.session_state.clear()
    st.rerun()

Build Issues

# Nuclear option: Clean everything
Bash: cd frontend && rm -rf node_modules build .vite
Bash: npm install
Bash: npm run build

# Python
Bash: rm -rf dist/ build/ *.egg-info
Bash: pip install -e .

Performance Guidelines

Minimize File Reads

Bad:

# Reading same file multiple times
Read: file.py  # Check structure
Read: file.py  # Get function definition
Read: file.py  # Find imports

Good:

# Read once, analyze in memory
Read: file.py
# Use content for all analysis

Batch Operations

Bad:

# Format files one by one
Bash: black file1.py
Bash: black file2.py
Bash: black file3.py

Good:

# Format all at once
Bash: black file1.py file2.py file3.py
# Or use glob
Bash: black streamlit_lightweight_charts_pro/**/*.py

Parallel Tool Calls

When operations are independent, run in parallel:

# Multiple independent tool calls in single message
Read: file1.py
Read: file2.py
Read: file3.py

# Not:
# Message 1: Read file1.py
# Message 2: Read file2.py
# Message 3: Read file3.py

Smart Search

Progressive refinement:

# Start broad
Grep: "render" → files_with_matches

# Narrow down
Read: <most promising files>

# Specific search
Grep: "render.*chart" → content

Agent-Specific Patterns

General Purpose Agent

Strengths:

• Multi-step workflows
• Complex problem solving
• Cross-file changes
• Documentation updates

Use for:

# Task: "Refactor series creation to use factory pattern"
1. Plan: Identify all series creation points
2. Design: Create factory interface
3. Implement: Update all call sites
4. Test: Ensure all series types still work
5. Document: Update architecture docs

Anti-patterns:

• Don't use for simple file searches (use Explore Agent)
• Don't use for quick architecture questions (use Explore Agent)

Explore Agent

Strengths:

• Fast codebase navigation
• Pattern discovery
• Quick architecture understanding

Use for:

# Task: "Find all error handling code"
Grep: "raise.*Error|except.*Error" → files_with_matches

# Task: "Show frontend component structure"
Glob: frontend/src/components/**/*.tsx

Anti-patterns:

• Don't use for code modifications
• Don't use for multi-step workflows

Plan Agent

Strengths:

• Architecture design
• Implementation strategy
• Trade-off analysis
• Critical path identification

Use for:

# Task: "Plan migration from React 18 to React 19"
→ Identify breaking changes
→ Find affected components
→ Design migration strategy
→ List testing requirements
→ Suggest rollback plan

Anti-patterns:

• Don't use for simple tasks
• Don't use for execution (only planning)

Decision Trees

"Should I use TodoWrite?"

Is this a multi-step task (≥3 steps)?
├─ Yes → Use TodoWrite
│  └─ Update on each step completion
└─ No → Skip TodoWrite
   └─ Just complete the task

"Which agent should I use?"

What's the task?
├─ Implement feature
│  ├─ Complex (multiple files, cross-cutting) → General Purpose
│  └─ Simple (single file, localized) → General Purpose
├─ Find information
│  ├─ Quick lookup → Explore
│  └─ Research/analysis → General Purpose
├─ Design approach
│  └─ Plan
└─ Fix bug
   ├─ Unknown location → Explore first, then General Purpose
   └─ Known location → General Purpose

"Should I run tests?"

Did I modify code?
├─ Yes
│  ├─ Python → pytest tests/ -v
│  └─ TypeScript → npm run test
└─ No → Skip tests

"Should I format code?"

Did I modify code?
├─ Yes
│  ├─ Python → isort, autoflake, black, ruff
│  └─ TypeScript → prettier, eslint
└─ No → Skip formatters

Best Practices Summary

DO

✅ Read files before editing ✅ Run formatters after every code change ✅ Write tests for new features ✅ Update documentation when APIs change ✅ Use absolute imports ✅ Follow Google-style docstrings ✅ Keep line width ≤ 100 characters ✅ Run tests before committing ✅ Use type hints (Python) and types (TypeScript) ✅ Add inline comments for complex logic

DON'T

❌ Don't skip formatters ❌ Don't commit failing tests ❌ Don't use relative imports ❌ Don't hardcode values without constants ❌ Don't ignore type errors ❌ Don't skip documentation ❌ Don't use any in TypeScript (unless necessary) ❌ Don't modify core dependencies directly ❌ Don't forget to update version numbers ❌ Don't skip changelog updates

Example Agent Workflows

Example 1: Add New Custom Primitive

# Agent: Plan
Task: "Design implementation for custom TooltipPrimitive"

Output:
1. Create primitive class in frontend/src/primitives/
2. Implement ISeriesPrimitive interface
3. Add attachment logic in LightweightCharts.tsx
4. Add Python wrapper in lightweight-charts-pro
5. Add tests
6. Add example

# Agent: General Purpose
Task: "Implement TooltipPrimitive following the plan"

Step 1: Create primitive
Edit: frontend/src/primitives/TooltipPrimitive.ts
[Implement primitive class]

Step 2: Register primitive
Edit: frontend/src/LightweightCharts.tsx
[Add attachment logic]

Step 3: Add tests
Edit: frontend/src/__tests__/primitives/TooltipPrimitive.test.ts
[Write tests]

Step 4: Format and verify
Bash: cd frontend && npm run code-quality
Bash: npm run test primitives/TooltipPrimitive

Example 2: Debug Performance Issue

# Agent: Explore
Task: "Find performance-critical rendering code"

Grep: "render|useEffect|useMemo" → files_with_matches
Read: frontend/src/LightweightCharts.tsx
Read: frontend/src/hooks/useSeriesUpdate.ts

# Agent: General Purpose
Task: "Analyze rendering performance"

Read: [critical files identified above]
Analysis:
- Series updates triggering full re-renders
- Missing memoization on expensive computations
- ResizeObserver firing too frequently

Recommendations:
1. Add useMemo to series factory
2. Debounce ResizeObserver
3. Use React.memo on child components

# Agent: General Purpose
Task: "Implement performance optimizations"

Edit: [Apply memoization]
Edit: [Add debouncing]
Edit: [Wrap components with React.memo]

Verify:
Bash: cd frontend && npm run test
Bash: npm run test:performance

Example 3: Migration Task

# Agent: Plan
Task: "Plan migration to use dev branch for dependencies"

Output:
1. Update pyproject.toml dependency URL
2. Verify dev branch exists
3. Test installation
4. Update documentation
5. Update CI/CD if needed

# Agent: General Purpose
Task: "Execute migration plan"

Step 1: Update dependency
Edit: pyproject.toml
  old: "@master"
  new: "@dev"

Step 2: Verify
Bash: git ls-remote https://github.com/nandkapadia/lightweight-charts-pro-python.git dev

Step 3: Test
Bash: pip install -e .

Step 4: Document
Edit: README.md
[Update installation instructions]

Edit: .claude/CLAUDE.md
[Update dependency information]

Troubleshooting Agent Tasks

Agent getting stuck

Symptoms: Repeating same actions, not making progress

Recovery:

1. Simplify the task into smaller steps
2. Provide explicit file paths
3. Use more specific search terms
4. Switch agent types (Explore → General Purpose)

Agent missing context

Symptoms: Making wrong assumptions, missing files

Recovery:

1. Provide architecture overview explicitly
2. List relevant files upfront
3. Give more context in task description
4. Use Plan Agent first to scope the work

Agent making too many changes

Symptoms: Touching unnecessary files, over-engineering

Recovery:

1. Be more specific in task description
2. Explicitly state "only modify X, don't touch Y"
3. Provide constraints upfront
4. Review plan before execution

Agent Collaboration Patterns

Sequential Agents

Plan Agent → Explore Agent → General Purpose Agent
1. Design approach
2. Find relevant files
3. Execute implementation

Parallel Agents

Multiple General Purpose Agents in parallel:
- Agent 1: Update Python code
- Agent 2: Update TypeScript code
- Agent 3: Update tests
- Agent 4: Update documentation

(Coordinate results at end)

Iterative Agents

General Purpose Agent (loop):
1. Implement feature chunk
2. Run tests
3. If tests fail, fix
4. Repeat until all tests pass

Remember: Agents are tools. Use the right agent for the task, provide clear instructions, and verify results. When in doubt, break complex tasks into smaller, manageable pieces.