From dc2dc0a5a1e1dc4f9f901464d689680eecc14011 Mon Sep 17 00:00:00 2001 From: Harel Tussi Date: Thu, 4 Sep 2025 13:00:24 +0300 Subject: [PATCH] docs: Add CLAUDE.md file for Claude Code guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Provides development commands, architecture overview, and essential information for future Claude Code instances working in this repository. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CLAUDE.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..94958627 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,77 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Development Commands + +This project uses Poetry for dependency management and Invoke for task automation. + +### Testing +- `invoke test` - Run unit tests +- `invoke test --coverage` - Run unit tests with coverage report +- `poetry run pytest` - Run tests directly with Poetry + +### Code Quality +- `invoke lint` - Run ruff linter (check only) +- `invoke lint --fix` - Run ruff linter with auto-fix +- `invoke formatter` - Check code formatting with black +- `invoke formatter --fix` - Format code with black +- `invoke staticcheck` - Run mypy type checking +- `invoke isort` - Run import sorting + +### Build & Package +- `invoke build` - Build the package with Poetry +- `poetry build` - Direct Poetry build command + +### Dependencies +- `invoke update` - Update all dependencies +- `invoke outdated` - Show outdated packages +- `invoke audit` - Run security audit with safety + +## Architecture Overview + +This is the AI21 Labs Python SDK, a comprehensive client library for interacting with AI21's language models across multiple deployment platforms. + +### Core Client Structure +- **Studio Client** (`ai21.AI21Client`): Primary client for AI21 Studio API +- **Bedrock Client** (`ai21.AI21BedrockClient`): AWS Bedrock integration +- **Azure Client** (`ai21.AI21AzureClient`): Azure AI Studio integration +- **Vertex Client** (`ai21.AI21VertexClient`): Google Cloud Vertex AI integration +- **Launchpad Client** (`ai21.AI21LaunchpadClient`): AI21 Launchpad platform + +All clients support both synchronous and asynchronous operations with corresponding `Async*` variants. + +### Key Features +- **Chat Completions**: Modern chat-based API with support for system/user/assistant roles +- **Maestro**: AI Planning & Orchestration System for enterprise workflows +- **Conversational RAG**: Chat with document retrieval from Studio library +- **Streaming**: Real-time response streaming for chat completions +- **File Management**: Upload and manage documents in Studio library + +### Module Organization +- `ai21/clients/` - Platform-specific client implementations +- `ai21/models/` - Pydantic models for requests/responses +- `ai21/http_client/` - HTTP layer with retry logic and error handling +- `ai21/stream/` - Streaming response handling +- `ai21/errors.py` - Custom exception hierarchy +- `examples/` - Usage examples for all platforms and features + +### Client Resources +Each client exposes resources through attributes: +- `client.chat.completions` - Chat completion API +- `client.beta.maestro.runs` - Maestro orchestration +- `client.library.files` - File upload/management +- `client.beta.conversational_rag` - RAG functionality + +### Environment Configuration +The SDK uses `AI21EnvConfig` for environment-based configuration supporting: +- `AI21_API_KEY` - Authentication +- `AI21_API_HOST` - Custom API endpoints +- `AI21_TIMEOUT_SEC` - Request timeouts +- `AI21_NUM_RETRIES` - Retry configuration +- `AI21_LOG_LEVEL` - Logging verbosity + +### Testing Structure +- `tests/unittests/` - Unit tests with mocking +- `tests/integration_tests/` - Live API integration tests +- Uses pytest with async support and mock fixtures \ No newline at end of file