From f7f4aa24d5fb960e959ef51767ef9cc672164738 Mon Sep 17 00:00:00 2001
From: Harel Tussi <harel2021@gmail.com>
Date: Thu, 18 Dec 2025 10:04:53 +0200
Subject: [PATCH] docs: add CLAUDE.md for AI assistant guidance
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Provide Claude Code with codebase context including build commands,
architecture overview, and environment configuration.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CLAUDE.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..cb42a64
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,62 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Development Commands
+
+```bash
+npm run build          # Build with Vite (outputs to dist/)
+npm test               # Run unit tests with Jest (includes coverage)
+npm run lint           # ESLint for src/ and examples/
+npm run format         # Prettier formatting
+npm run quality        # Full quality check: circular deps, lint, typecheck, format, unused deps
+npm run quality:fix    # Same as quality but auto-fixes lint and format issues
+npm run circular       # Check for circular dependencies with madge
+npm run integration-test  # Run integration tests (requires AI21_API_KEY)
+```
+
+### Running a Single Test
+```bash
+npx jest tests/unittests/resources/chat/completions.test.ts
+npx jest --testNamePattern="test name pattern"
+```
+
+## Architecture Overview
+
+This is the official AI21 Labs TypeScript SDK for the Jamba model family. It supports both Node.js (>=18) and browser environments.
+
+### Core Structure
+
+- **`AI21`** (src/AI21.ts) - Main client class extending `APIClient`. Exposes resources: `chat`, `conversationalRag`, `library`, `beta` (Maestro)
+- **`APIClient`** (src/APIClient.ts) - Abstract base with HTTP methods (get/post/put/delete/upload), retry logic, and request handling
+- **`APIResource`** (src/APIResource.ts) - Base class for all resource modules
+
+### Resources (src/resources/)
+
+- **chat/** - Chat completions API with streaming support
+- **rag/** - Conversational RAG for Q&A over uploaded files
+- **library/** - File management for RAG system
+- **maestro/** - Beta orchestration platform with tools (web_search, file_search)
+
+### Platform Abstraction
+
+The SDK uses runtime detection to provide consistent behavior across environments:
+
+- **fetch/** - `NodeFetch` vs `BrowserFetch` implementations
+- **files/** - `NodeFilesHandler` vs `BrowserFilesHandler` for form data
+- **runtime.ts** - `isBrowser` / `isNode` detection utilities
+
+### Type System (src/types/)
+
+Types are organized by domain: `chat/`, `rag/`, `files/`, `maestro/`. All exports flow through index files.
+
+### Streaming (src/streaming/)
+
+SSE-based streaming for chat completions. `Stream` class implements async iterator pattern for `for await` consumption.
+
+## Environment Variables
+
+- `AI21_API_KEY` - API key (required)
+- `AI21_BASE_URL` - Override API endpoint (default: https://api.ai21.com/studio/v1)
+- `AI21_TIMEOUT_SEC` - Request timeout in seconds
+- `AI21_LOG_LEVEL` - Logging level