arshai: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Testing

poetry run pytest                    # Run all tests
poetry run pytest tests/unit/        # Run unit tests only
poetry run pytest tests/integration/ # Run integration tests only
poetry run pytest --cov=arshai      # Run tests with coverage

Code Quality

poetry run black .                  # Format code
poetry run isort .                  # Sort imports
poetry run mypy arshai/             # Type checking
poetry run bandit -r arshai/        # Security analysis
poetry run safety check             # Check dependencies for vulnerabilities

Documentation

cd docs_sphinx && make html  # Build Sphinx documentation

Package Management

poetry install           # Install all dependencies
poetry install -E all    # Install with all optional dependencies (redis, milvus, flashrank)
poetry install -E docs   # Install documentation dependencies

Architecture Overview

Arshai is an AI application framework built on clean architecture principles with interface-driven design. The system follows a layered approach with clear separation of concerns:

Core Layers

1. Application Layer: Workflows and Agents that orchestrate business logic
2. Domain Layer: Memory, Tools, and LLM integrations that handle core functionality
3. Infrastructure Layer: Document processing, vector storage, and external integrations

Key Components

• Agents (arshai/agents/): Intelligence units that process user interactions
• Workflows (arshai/workflows/): Orchestrate complex multi-step processes with state management
• Memory (arshai/memory/): Handle conversation context and state persistence
• Tools (arshai/tools/): External capabilities that extend agent functionality
• LLMs (arshai/llms/): Language model integrations with unified interface
• Factories (arshai/factories/): Component creation and dependency injection