mirror of https://github.com/kortix-ai/suna.git
146 lines
5.1 KiB
Plaintext
146 lines
5.1 KiB
Plaintext
---
|
|
alwaysApply: true
|
|
---
|
|
|
|
# Suna AI Worker Project - Cursor Rules
|
|
|
|
## Project Overview
|
|
|
|
Suna is an open-source generalist AI Worker with a full-stack architecture:
|
|
|
|
- **Frontend**: Next.js 15+ with TypeScript, Tailwind CSS, Radix UI, React Query
|
|
- **Backend**: Python 3.11+ with FastAPI, Supabase, Redis, LiteLLM, Dramatiq
|
|
- **Agent System**: Isolated Docker environments with comprehensive tool execution
|
|
- **Database**: Supabase for persistence, authentication, real-time features, and RLS
|
|
|
|
## Architecture Components
|
|
|
|
### Core Stack
|
|
|
|
- **Frontend**: Next.js App Router + TypeScript + Tailwind + Radix UI
|
|
- **Backend**: FastAPI + Supabase + Redis + LiteLLM + Dramatiq workers
|
|
- **Database**: PostgreSQL via Supabase with Row Level Security
|
|
- **Agent Runtime**: Docker containers with browser automation, code interpreter
|
|
- **Authentication**: Supabase Auth with JWT validation
|
|
- **Monitoring**: Langfuse tracing, Sentry error tracking, Prometheus metrics
|
|
|
|
### File Organization
|
|
|
|
```txt
|
|
project/
|
|
├── frontend/ # Next.js application
|
|
│ └── src/
|
|
│ ├── app/ # Next.js app router pages
|
|
│ ├── components/ # Reusable React components
|
|
│ ├── hooks/ # Custom React hooks
|
|
│ ├── lib/ # Utilities and configurations
|
|
│ ├── providers/ # Context providers
|
|
│ └── contexts/ # React contexts
|
|
├── backend/ # Python FastAPI backend
|
|
│ ├── agent/ # AI Worker core implementation
|
|
│ ├── services/ # Business logic services
|
|
│ ├── utils/ # Shared utilities
|
|
│ ├── supabase/ # Database migrations & config
|
|
│ ├── tools/ # Agent tool implementations
|
|
│ ├── auth/ # Authentication logic
|
|
│ ├── triggers/ # Event-driven triggers
|
|
│ └── api.py # Main FastAPI application
|
|
└── docs/ # Documentation
|
|
```
|
|
|
|
## Development Principles
|
|
|
|
### Code Quality Standards
|
|
|
|
- **Type Safety**: Strict TypeScript frontend, comprehensive Python type hints
|
|
- **Error Handling**: Structured error responses, proper exception handling
|
|
- **Logging**: Structured logging with context throughout the stack
|
|
- **Testing**: Unit tests for core logic, integration tests for APIs
|
|
- **Security**: Input validation, authentication, encryption for sensitive data
|
|
|
|
### Performance Guidelines
|
|
|
|
- **Frontend**: Code splitting, lazy loading, optimized bundle size
|
|
- **Backend**: Async/await patterns, connection pooling, Redis caching
|
|
- **Database**: Proper indexing, query optimization, RLS policies
|
|
- **Agent**: Timeout handling, resource limits, sandbox isolation
|
|
|
|
### Integration Patterns
|
|
|
|
- **LLM Integration**: LiteLLM for multi-provider support, structured prompts
|
|
- **Tool System**: Dual schema decorators (OpenAPI + XML), consistent ToolResult
|
|
- **Real-time**: Supabase subscriptions for live updates
|
|
|
|
## Key Technologies
|
|
|
|
### Frontend Dependencies
|
|
|
|
- Next.js 15+, React 18+, TypeScript 5+
|
|
- @tanstack/react-query, @supabase/supabase-js
|
|
- @radix-ui components, @tailwindcss/typography
|
|
- @hookform/resolvers, react-hook-form
|
|
|
|
### Backend Dependencies
|
|
|
|
- FastAPI 0.115+, Python 3.11+
|
|
- Supabase 2.17+, Redis 5.2+, LiteLLM 1.72+
|
|
- Dramatiq 1.18+, Pydantic for validation
|
|
- Sentry, Langfuse, Prometheus for observability
|
|
|
|
## Advanced Patterns
|
|
|
|
### Agent System Architecture
|
|
|
|
- **Versioning**: Multiple agent versions with `agent_versions` table
|
|
- **Configuration**: JSONB config storage with validation
|
|
- **Workflows**: Step-by-step execution with `agent_workflows`
|
|
- **Triggers**: Scheduled and event-based automation
|
|
- **Builder Tools**: Dynamic agent creation and management
|
|
|
|
### Security & Authentication
|
|
|
|
- **JWT Validation**: Supabase token verification without signature check
|
|
- **Row Level Security**: Database-level access control
|
|
- **Credential Encryption**: Secure storage of sensitive API keys
|
|
- **Input Validation**: Pydantic models for all user inputs
|
|
|
|
### Database Patterns
|
|
|
|
- **Migrations**: Idempotent SQL with proper error handling
|
|
- **Indexing**: Foreign keys and query optimization
|
|
- **Triggers**: Automated timestamp management
|
|
- **Enums**: Safe enum creation with duplicate handling
|
|
|
|
## Development Workflow
|
|
|
|
### Environment Setup
|
|
|
|
- Use `mise.toml` for tool version management
|
|
- Docker Compose for local development stack
|
|
- Environment-specific configurations (LOCAL/STAGING/PRODUCTION)
|
|
|
|
### Code Standards
|
|
|
|
- Follow established naming conventions
|
|
- Implement proper error boundaries
|
|
- Use consistent logging patterns
|
|
- Handle loading and error states
|
|
|
|
### Testing Strategy
|
|
|
|
- Unit tests for business logic
|
|
- Integration tests for API endpoints
|
|
- E2E tests for critical user flows
|
|
- Performance testing for agent execution
|
|
|
|
## When in Doubt
|
|
|
|
- Follow existing patterns in the codebase
|
|
- Check similar implementations for guidance
|
|
- Use established error handling and logging
|
|
- Prioritize type safety and security
|
|
- Consult domain-specific rule files for detailed guidance
|
|
- Check similar implementations for guidance
|
|
- Use the established error handling patterns
|
|
- Follow the logging conventions with structured logging
|