feat: Make support for querying states

[NiveditJain]

As a user, I want to query states based on inputs, outputs, graphs, and other criteria, then see that execution path in detail.

Motivation

Currently, users can view individual nodes and their details, but there's no way to search or filter states based on specific criteria. This makes it difficult to:

1. Find specific executions – Locate states that match certain input/output values or patterns
2. Debug workflows – Trace execution paths for states with specific characteristics
3. Analyze workflow behavior – Query states across different graphs, runs, or time periods
4. Monitor specific conditions – Find states that meet certain criteria (e.g., error states, specific input values, etc.)

Current State

What Exists

Component	Location	Purpose
State model	state-manager/app/models/db/state.py	Database model for states with fields: inputs, outputs, graph_name, run_id, status, etc.
ListStatesResponse	state-manager/app/models/...	API response for listing states
Graph visualization	dashboard/src/components/GraphVisualization.tsx	Visual representation of graph execution
Node details	dashboard/src/components/NodeDetailsModal.tsx	Detailed view of individual nodes
State list endpoints	state-manager/app/routes.py	Basic state listing functionality

Current Limitations

• No query/filter capabilities for states based on inputs, outputs, or other fields
• Cannot search states by specific criteria
• Limited ability to trace execution paths for filtered states
• No way to find states matching specific patterns or values
• Graph visualization shows all nodes, but cannot filter to specific execution paths

Proposed Solution

Overview

Add a comprehensive query API for states that allows filtering by:

• Inputs – Query states where inputs match specific key-value pairs or patterns
• Outputs – Query states where outputs match specific criteria
• Graph – Filter by graph name
• Run ID – Filter by specific execution run
• Status – Filter by state status (CREATED, QUEUED, SUCCESS, ERRORED, etc.)
• Node name/identifier – Filter by specific node types
• Time range – Filter by created_at or updated_at timestamps
• Other metadata – Additional state fields as needed

After querying, users should be able to:

• View the filtered states in a list
• See the execution path for queried states
• Navigate to detailed views of specific states
• Visualize the execution path in the graph view

Key Features

1. Query API – RESTful endpoint for querying states with flexible filters
2. Query Builder UI – Dashboard interface for building and executing queries
3. Results Display – List view of matching states with key information
4. Execution Path Visualization – Show the execution path for queried states in the graph view
5. Export/Share – Ability to export query results or share query configurations

UI Components

1. Query Builder Panel:

   • Form-based interface for building queries
   • Add/remove filter conditions
   • Support for different filter types
   • Save/load query presets

2. Results Table:

   • Paginated list of matching states
   • Sortable columns
   • Quick actions (view details, show in graph)
   • Export functionality

3. Execution Path View:

   • Filter graph visualization to show only queried states
   • Highlight execution paths
   • Show connections between states
   • Navigate to node details

Acceptance Criteria

• Query API endpoint supports filtering by:
  • Graph name
  • Run ID
  • Status
  • Node name/identifier
  • Inputs (exact match, nested fields)
  • Outputs (exact match, nested fields)
  • Time ranges (created_at, updated_at)
  • Other state fields
• Query API supports pagination and sorting
• Query results include total count and pagination metadata
• Dashboard has query builder UI for constructing queries
• Dashboard displays query results in a table/list view
• Users can view execution path for queried states in graph view
• Graph view highlights/filters to show only queried states
• Users can navigate from query results to node details
• Query builder supports saving/loading query presets
• Query results can be exported (CSV, JSON, etc.)
• Performance is acceptable for large result sets (pagination, indexing)

Testing Considerations

1. Backend Tests:

   • Test various filter combinations
   • Test nested field queries (inputs/outputs)
   • Test pagination and sorting
   • Test edge cases (empty results, invalid filters)
   • Test performance with large datasets

2. Frontend Tests:

   • Test query builder form validation
   • Test query execution and result display
   • Test graph filtering and path highlighting
   • Test navigation from results to details
   • Test export functionality

3. Integration Tests:

   • End-to-end query flow
   • Query → Results → Graph view → Node details
   • Performance testing with realistic data volumes

Related Issues

• Issue feat: Show next run time of state #611: Show next run time of state
• Issue feat: Trigger execution of a graph from dashboard #609: Trigger execution from dashboard
• Issue feat: Add UI based workflow builder #636: UI workflow builder

Notes

• This feature significantly enhances observability and debugging capabilities
• Consider rate limiting for query endpoints to prevent abuse
• May need to add database indexes for optimal performance
• Query syntax should be flexible but secure (prevent injection attacks)
• Consider adding query result caching for frequently used queries
• Graph visualization may need optimization for large execution paths