mirror of
https://github.com/bendtherules/ask262.git
synced 2026-08-18 13:21:55 +00:00
bendtherules
627b80008e
Add Langfuse as an OTel trace transport for MCP request lifecycle tracking.
Changes:
- New src/lib/langfuse-transport.ts: initializes LangfuseSpanProcessor when
ASK262_LANGFUSE_ENABLED=true with valid credentials
- src/lib/tracing.ts: add metadata to TraceContext, propagate it to child spans,
use startActiveSpan for proper OTel context, add setupTracing() entry point,
add getSessionMetadata() for version/transport metadata
- src/lib/logger.ts: include TraceContext.metadata in JSON log mixin
- src/mcp-server-{http,stdio}.ts: call setupTracing() at startup, pass
version/transport metadata through withSpan/withSpanContext
- src/lib/fireworks-embeddings.ts: wrap API calls in withSpan() with gen_ai
attributes for Langfuse generation/cost tracking
- .env.example: add LANGFUSE_* configuration variables
- AGENTS.md: document Langfuse integration
- package.json: add @langfuse/tracing, @langfuse/otel, @opentelemetry/sdk-node
85 lines
3.3 KiB
Markdown
85 lines
3.3 KiB
Markdown
# AGENTS.md - Ask262 Project Guide
|
|
|
|
## Project Overview
|
|
|
|
**Ask262** is a RAG-based MCP server for exploring the ECMAScript specification via [engine262](https://github.com/bendtherules/engine262). Users ask questions like *"How does array.map work?"* and get answers grounded in the actual spec and implementation.
|
|
|
|
**Stack:** Vector search (LanceDB + Ollama/Fireworks embeddings) → Knowledge graph → LLM reasoning. Runs as MCP server (stdio or HTTP) for Claude Desktop, OpenCode, etc.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
bun run ingest # Ingest spec HTML into vector DB
|
|
bun run build # Build knowledge graph
|
|
bun run lint # Biome check
|
|
bun run type-check # TypeScript strict check
|
|
bun test # Run all Bun tests
|
|
bun run ask262-stdio # Stdio transport
|
|
bun run ask262-http # HTTP transport (port 8081)
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
**Core:**
|
|
`src/agent-tools/` - MCP tool implementations
|
|
`src/mcp-server-stdio.ts` - Stdio server entry
|
|
`src/mcp-server-http.ts` - HTTP server entry
|
|
|
|
**Data:**
|
|
`storage/` - LanceDB vector index
|
|
`spec-built/multipage/` - ECMAScript spec HTML
|
|
`engine262/` - JS engine implementation (git submodule, ignored)
|
|
`graphology/` - Knowledge graph JSON
|
|
|
|
**Setup:**
|
|
`src/setup/ingest.ts` - Creates vector DB from spec
|
|
`src/setup/buildGraph.ts` - Maps spec sections to code
|
|
|
|
## Code Style
|
|
|
|
**Imports:** ES modules only. Node built-ins use `node:` prefix. Never CommonJS.
|
|
|
|
**Formatting (Biome):** 2 spaces, 80 char width, LF endings. Excludes: `spec-built/`, `engine262/`, `graphology/`.
|
|
|
|
**TypeScript:** Strict mode enabled. Explicit return types. Avoid `any`. Target: ES2022.
|
|
|
|
**Naming:** Folders kebab-case (`agent-tools`). Files camelCase (`buildGraph.ts`). Functions camelCase (`createTool`). Constants UPPER_SNAKE_CASE. Types PascalCase.
|
|
|
|
**Error Handling:** Try/catch with meaningful messages. Validate env vars. Log warnings for missing config.
|
|
|
|
**Comments & Documentation:**
|
|
- JSDoc for public functions: purpose, params, return values, examples
|
|
- Use `/** */` for documentation blocks
|
|
- Use `//` for inline implementation notes
|
|
- Document complex logic or non-obvious decisions
|
|
|
|
## Environment
|
|
|
|
Copy `.env.example` to `.env`:
|
|
- `ASK262_EMBEDDING_PROVIDER` - `ollama` or `fireworks`
|
|
- `FIREWORKS_API_KEY` - Required for Fireworks
|
|
- `OLLAMA_HOST` - Ollama URL (default: http://localhost:11434)
|
|
- `ASK262_PORT` - HTTP server port (default: 8081)
|
|
- `MCP_PUBLIC_URL` - Public URL for inspector
|
|
- `ASK262_LANGFUSE_ENABLED` - Enable Langfuse tracing (optional)
|
|
- `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` - Langfuse credentials (required when enabled)
|
|
|
|
## Key Dependencies
|
|
|
|
- **LanceDB** - Vector storage
|
|
- **Ollama** / **Fireworks** - Embeddings
|
|
- **LangChain** - LLM framework
|
|
- **Hono** - HTTP server
|
|
- **Biome** - Lint/format
|
|
|
|
## Important Notes
|
|
|
|
- TypeScript only - no plain JS
|
|
- Run `bun run type-check` before committing
|
|
- Ingest/build are slow (local embedding generation)
|
|
- Don't lint/format external dirs (`engine262/`, `spec-built/`, `graphology/`)
|
|
|
|
## Observability
|
|
|
|
Ask262 uses OpenTelemetry for tracing. When `ASK262_LANGFUSE_ENABLED=true` is set with valid Langfuse credentials, all OTel spans are exported to Langfuse automatically. No code changes are needed — it's purely a transport configuration. Metadata (version, transport type) is attached to every trace and included in both Langfuse and JSON logs.
|