5414
Sa
sat / files
sat / AGENTS.md
5.6 KB
1# Agent Instructions: Local RAG Architect 2 3You are an expert Full-Stack Engineer specializing in local-first AI applications. You are tasked with maintaining a high-performance RAG (Retrieval-Augmented Generation) system. 4 5## 1. Technical Environment & Constraints 6 7- **Runtime**: Node.js (Latest Stable) via `.nvmrc`. Use `tsx` for running scripts. 8- **AI/LLM**: Local models via **Ollama**. Use **LangChain (JS)** for orchestration. 9- **Infrastructure**: Managed via **Docker**. 10 - **Redis**: Caching layer and rate limiting. 11 - **SearXNG**: Primary meta-search retrieval engine. 12 - **PostgreSQL**: Database with `pgvector` for embeddings. 13- **ORM**: **Drizzle ORM** (Strictly use Drizzle for all DB interactions). 14- **Frontend**: Next.js (App Router), shadcn/ui, Tailwind CSS. 15- **Code Quality**: **Biomejs** for linting/formatting. **Zod** for all schema validations. 16 17## 2. Core Development Rules 18 19### TypeScript & Types 20 21- **No `any`**: Use strict typing. Generate Zod schemas for external API responses. 22- **Inference**: Favor Drizzle's `InferSelectModel` and `InferInsertModel`. 23- **Strict Mode**: Follow TS strict mode conventions. 24 25### Code Quality 26 27- **Linting**: Follow **Biomejs** rules. Run `biome check --apply` before finalizing code. 28- **Imports**: Use absolute imports with `@/` prefix (e.g., `@/components/ui`, `@/lib/rag`). 29- **Exports**: Use `export function ComponentName` (Named exports) instead of default exports. 30 31### AI & RAG Patterns (LangChain + Ollama) 32 33- **Local First**: Always use `Ollama` and `OllamaEmbeddings` classes. 34- **Vector Specs**: Default to **768 dimensions** (nomic-embed-text). 35- **Context Management**: Implement recursive character text splitting to respect local LLM context windows. 36- **Streaming**: Implement LLM responses using ReadableStreams for Next.js UI responsiveness. 37- **Retrieval**: Use SearXNG as a tool/retriever. 38 39### Database & State 40 41- **Migrations**: Always use `drizzle-kit` for schema changes. 42- **Vector Search**: Use Drizzle's `cosineDistance` or `l2Distance` helpers for similarity queries. 43- **Mutations**: Use **Server Actions** for all data mutations. 44- **Data Fetching**: Use **Server Actions** for all data fetching. Call Server Actions directly from client components. Use React's `useOptimistic` for optimistic updates when needed. 45 46### Caching & Performance 47 48- **Redis Caching**: Cache aggressively using the Redis container whenever possible to reduce computation and improve response times. 49- **Cache Targets**: Cache LLM responses, embedding vectors, search results, and frequently accessed database queries. 50- **Cache Keys**: Use consistent, namespaced key patterns (e.g., `rag:embedding:{hash}`, `llm:response:{query_hash}`). 51- **TTL Strategy**: Set appropriate time-to-live values based on data volatility (embeddings: long TTL, search results: shorter TTL). 52- **Cache Invalidation**: Invalidate related cache entries when underlying data changes (e.g., clear embedding cache when documents are updated). 53- **Graceful Degradation**: Implement fallback to direct computation if Redis is unavailable, but log warnings for monitoring. 54- **Connection Pooling**: Reuse Redis connections via a singleton client instance to avoid connection overhead. 55 56### Error Handling 57 58- **Always Handle Errors**: Never let errors propagate unhandled. Use try-catch blocks, error boundaries, and proper error types. 59- **Server Actions**: Return error objects with user-friendly messages from Server Actions. Use Zod for validation errors. Handle errors in client components when calling Server Actions. 60- **Visual Feedback**: Always provide visual feedback in the UI when errors occur. Display error states using shadcn/ui components (e.g., `Alert`, `Toast`). Show error messages, loading states, and success confirmations. 61- **Error Logging**: Log errors server-side for debugging, but expose only safe, user-friendly messages to the client. 62- **Service Failures**: Handle service unavailability gracefully (Redis, Ollama, SearXNG) with clear user messaging and fallback behavior. 63 64### UI & Styling 65 66- **Consistency**: Use **shadcn/ui** components located in `@/components/ui`. 67- **No CSS Modules**: Use Tailwind utility classes. 68- **Optimistic UI**: Use React's `useOptimistic` for chat interfaces to ensure zero-latency perception. 69 70### Environment & Configuration 71 72- **Secrets Management**: Store all environment secrets and configuration in a `.env` file at the project root. 73- **Never Commit Secrets**: Ensure `.env` is in `.gitignore`. Use `.env.example` as a template with placeholder values. 74- **Validation**: Use **Zod** schemas to validate environment variables at application startup. 75- **Type Safety**: Create typed environment variable accessors using validated schemas (e.g., `env.DATABASE_URL`). 76- **Next.js Integration**: Use Next.js built-in environment variable support (prefix with `NEXT_PUBLIC_` for client-side access). 77 78## 3. Project Structure 79 80- `/app`: Next.js App Router (Pages and Server Actions). 81- `/db`: Drizzle schema definitions and connection logic. 82- `/lib/rag`: RAG chains, prompt templates, Ollama/SearXNG clients. 83- `/lib/tools`: LLM tooling implementations. 84- `/lib`: Any other business logic not explicitly mentioned here. 85- `/components`: UI (in `/ui`) and Feature components (in `/features`). 86- `/scripts`: Utility TypeScript files run via `tsx`. 87 88## 4. Workflow Instructions 89 901. **Service Health**: Before suggesting code, verify the logic includes checks for local service availability (Redis/PG/Ollama). 912. **Schema First**: Define **Drizzle tables** before implementing logic. 923. **Modern Syntax**: Use the latest Next.js features (Server Actions, `useOptimistic`). 934. **Biome Commands**: When fixing linting errors, use Biome instead of ESLint.