AGENTS.md

1# Agent Guidelines for OpenSearch Project
2 
3## Build/Test Commands
4- **Run dev**: `bun run dev` (watches src/index.ts)
5- **Run CLI**: `bun run cli` (starts interactive CLI)
6- **Run tests**: `bun test` (runs all tests)
7- **Run single test**: `bun test <test-file>` (e.g., `bun test test/generate-query.test.ts`)
8- **Format/Lint**: Use Biome via `bunx biome format .` and `bunx biome lint .`
9 
10## Code Style & Conventions
11- **Runtime**: Use Bun instead of Node.js/npm/pnpm (see .cursor/rules)
12- **Formatting**: Tabs for indentation, single quotes for strings (biome.json)
13- **Imports**: Organize imports enabled, use path aliases `@/*` for src, `@baml-client` for BAML
14- **Types**: Strict TypeScript, interfaces for data structures, explicit return types
15- **Naming**: PascalCase for React components/BAML functions, camelCase for variables/functions
16- **Files**: .tsx for React components, .ts for utilities, .baml for BAML functions
17 
18## BAML Integration
19- **Source files**: Only edit files in `baml_src/` directory (*.baml files)
20- **Generated code**: `baml_client/` is auto-generated from `baml_src/` - never edit directly
21- **Functions**: Import and call via `import { b } from '@baml-client'; await b.SomeFunction(...)`
22- **Types**: All classes/enums exported from `@baml-client` (e.g., `import { SearchResult } from '@baml-client'`)
23- **Naming**: BAML functions use PascalCase (e.g., `GenerateQuery`, `Reflect`)
24- **Prompts**: Include `{{ ctx.output_format }}` and `{{ _.role("user") }}` for user inputs
25- **Schema**: Prefer enums over confidence numbers, use classes for structured outputs
26 
27## Error Handling & Testing
28- Use Bun's built-in test framework with `import { test, expect } from "bun:test"`
29- Async/await for BAML function calls and API interactions
30- Type-safe error handling with proper TypeScript types