xonecas.io
53129
Pa

PAT / commit 9635232

fix: rework agents file

xonecas2025-12-16 9635232ce5d058b54422dea73ecc674564047a56 parent 5e84abc

2 files changed

AGENTS.md+167−4
@@ -2,9 +2,172 @@
22
33 This is a personal assistant project, that renders a simple assistant chat layout as a web page, and provides access to an agentic model running locally via ollama. The project uses Next.js for it's typescript framework TailwindCSS for it's styling, and Ollama's typescript/javascript library itself for querying the model. This project is also responsible for augmenting the model's prompt with search results from DuckDuckGo.
44
5+## Project Commands
6+
7+All commands should be run from the project root directory:
8+
9+- **Development Server**: `npm run dev` - Starts the Next.js development server
10+- **Build**: `npm run build` - Builds the production-ready Next.js application
11+- **Start Production**: `npm run start` - Starts the production server (requires build first)
12+- **Lint**: `npm run lint` - Runs ESLint to check code quality
13+
514 ## Dependencies
615
7-- **DuckDuckGo Instant Answer API** | Unlimited (no key) | Very lightweight; returns JSON with snippets for most queries. | <https://api.duckduckgo.com/api>
8-- **Ollama** | locally or via an API, running your model of choice (gpt-oss is a good starter) | <https://ollama.com>
9-- **Next.js** | typescript framework for the web UI/server | <https://nextjs.org/docs>
10-- **TailwindCSS** | UI styling | <https://tailwindcss.com/>
16+### Production Dependencies
17+
18+Agents MUST use only these existing dependencies. Do NOT add new dependencies without explicit approval:
19+
20+- **next**: ^16.0.10 - Next.js framework
21+- **react**: 18.2.0 - React library
22+- **react-dom**: 18.2.0 - React DOM rendering
23+- **tailwindcss**: ^3.4.0 - Utility-first CSS framework
24+- **typescript**: ^5.4.2 - TypeScript compiler
25+- **ollama**: ^0.6.3 - Official Ollama npm package for model interaction
26+- **autoprefixer**: ^10.4.17 - CSS post-processor
27+- **postcss**: ^8.4.30 - CSS transformation tool
28+
29+### Dev Dependencies
30+
31+- **@types/node**: ^20.11.18 - TypeScript types for Node.js
32+- **@types/react**: ^18.2.55 - TypeScript types for React
33+- **@types/react-dom**: ^18.2.19 - TypeScript types for React DOM
34+- **eslint**: ^8.56.0 - JavaScript/TypeScript linter
35+- **eslint-config-next**: ^13.5.6 - Next.js ESLint configuration
36+
37+## Code Style Guidelines
38+
39+### TypeScript Configuration
40+
41+- **Strict Mode**: Disabled (`strict: false` in tsconfig.json)
42+- **Target**: ES2017
43+- **Module**: ESNext
44+- **JSX**: React JSX transform (`react-jsx`)
45+
46+### Code Style Rules
47+
48+1. **File Organization**:
49+ - Use Next.js App Router structure (`app/` directory)
50+ - API routes in `app/api/[route]/route.ts`
51+ - Library utilities in `src/lib/`
52+ - Use TypeScript for all code files (`.ts`, `.tsx`)
53+
54+2. **Component Style**:
55+ - Use functional components with React hooks
56+ - Use `"use client"` directive for client components
57+ - Export default for page components
58+ - Use named exports for utility functions
59+
60+3. **Naming Conventions**:
61+ - Functions: `camelCase` (e.g., `fetchOllamaResponse`, `sendMessage`)
62+ - Components: `PascalCase` (e.g., `Home`, `RootLayout`)
63+ - Interfaces: `PascalCase` (e.g., `DuckDuckGoResult`)
64+ - Constants: `UPPER_SNAKE_CASE` or `camelCase` depending on scope
65+
66+4. **TypeScript Types**:
67+ - Use interfaces for object shapes
68+ - Use type annotations for function parameters and return types
69+ - Prefer explicit types over `any`
70+ - Use JSDoc comments for function documentation
71+
72+5. **Async/Await**:
73+ - Always use `async/await` instead of promises with `.then()`
74+ - Use `try/catch` for error handling in async functions
75+ - API routes should return `NextResponse` objects
76+
77+6. **Styling**:
78+ - Use TailwindCSS utility classes exclusively
79+ - Inline Tailwind classes in JSX
80+ - Follow existing patterns: `className="flex flex-col bg-gray-100 p-4"`
81+ - Use responsive design utilities when appropriate
82+
83+7. **Code Formatting**:
84+ - Use consistent indentation (2 spaces)
85+ - Use single quotes for strings in some contexts, double quotes in others (maintain existing file style)
86+ - Add trailing commas in multi-line objects/arrays
87+ - Use semicolons
88+
89+8. **Error Handling**:
90+ - Use `console.error` for errors
91+ - Use `console.debug` for debug information
92+ - Return user-friendly error messages in API responses
93+ - Handle API errors gracefully with try/catch blocks
94+
95+9. **File Headers**:
96+ - Optional: Add file path comments at the top of library files (e.g., `/* personal-assistant-thing/src/lib/ollama.ts */`)
97+
98+10. **Imports**:
99+ - Use relative imports for local files
100+ - Group imports: external packages first, then local imports
101+ - Use named imports from libraries (e.g., `import { NextResponse } from "next/server"`)
102+
103+## Project Structure
104+
105+```
106+/home/xonecas/src/personal-assistant-thing/
107+├── app/
108+│ ├── api/
109+│ │ └── chat/
110+│ │ └── route.ts # Chat API endpoint
111+│ ├── globals.css # Global styles
112+│ ├── layout.tsx # Root layout component
113+│ └── page.tsx # Main page component
114+├── src/
115+│ └── lib/
116+│ ├── duckduckgo.ts # DuckDuckGo API wrapper
117+│ └── ollama.ts # Ollama API wrapper
118+├── package.json
119+├── tsconfig.json
120+└── tailwind.config.js
121+```
122+
123+## Key Implementation Details
124+
125+### UI Style
126+
127+- Always ensure support for both light and dark modes
128+- Use grays for backgrounds, and darker grey borders
129+- Don't use round corners
130+- The UI should always fit to the available space
131+- Primary colors: sky-400 for dark mode, cyan-900 for light mode
132+- Alternate colors: indigo at an appropriate shade for current mode
133+
134+### Ollama Integration
135+
136+- Default model: `gpt-oss`
137+- Function: `fetchOllamaResponse(prompt: string, model?: string)`
138+- Returns: Promise<string> with the model's response
139+- Located in: `src/lib/ollama.ts`
140+
141+### DuckDuckGo Integration
142+
143+- Endpoint: `https://api.duckduckgo.com/`
144+- Function: `fetchDuckDuckGo(query: string)`
145+- Returns: Promise<DuckDuckGoResult[]>
146+- Interface: `{ title: string; snippet: string; url: string }`
147+- Located in: `src/lib/duckduckgo.ts`
148+
149+### Chat API Flow
150+
151+1. Client sends POST request to `/api/chat` with `{ message: string }`
152+2. API route fetches DuckDuckGo results for the message
153+3. API route builds prompt with message + search results
154+4. API route calls Ollama with the augmented prompt
155+5. API route returns `{ answer: string }`
156+
157+## Development Workflow
158+
159+1. Start development server: `npm run dev`
160+2. Make code changes
161+3. Test in browser (typically `http://localhost:3000`)
162+4. Run linter: `npm run lint`
163+5. Build for production: `npm run build`
164+
165+## Important Constraints
166+
167+- **DO NOT** add new npm packages without explicit approval
168+- **DO NOT** change TypeScript strict mode settings
169+- **DO NOT** modify Next.js or React versions
170+- **DO NOT** Commit secrets or API keys, edit `node_modules/` or `vendor/`
171+- **DO** maintain existing code style and patterns
172+- **DO** use existing utility functions from `src/lib/`
173+- **DO** follow the App Router conventions for Next.js 16
_planning/TODO.md+0−0