xonecas.io
5414
Sa

sat / commit 2dc42b4

chore: agents.md file

Sean2026-01-13 2dc42b4acecf6ec5f0513970351818fe03fbc8ea parent 135137c

2 files changed

.nvmrc+1−0
@@ -0,0 +1 @@
1+stable
AGENTS.md+93−0
@@ -0,0 +1,93 @@
1+# Agent Instructions: Local RAG Architect
2+
3+You 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+
90+1. **Service Health**: Before suggesting code, verify the logic includes checks for local service availability (Redis/PG/Ollama).
91+2. **Schema First**: Define **Drizzle tables** before implementing logic.
92+3. **Modern Syntax**: Use the latest Next.js features (Server Actions, `useOptimistic`).
93+4. **Biome Commands**: When fixing linting errors, use Biome instead of ESLint.