xonecas.io
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.