# CLAUDE.md

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

## Project Overview

**kguru** is an AI agent platform for Python with domain-specific knowledge capabilities. It implements a STAR framework (See → Think → Act → Reflect) for intelligent problem-solving with support for multiple LLM providers.

Published on PyPI: https://pypi.org/project/kguru/

## Development Commands

### Initial Setup
```bash
make setup
```
This installs Python 3.12 (if needed), creates a virtual environment, installs dependencies, and sets up pre-commit hooks.

### Code Quality
```bash
make format    # Auto-format code with ruff
make lint      # Lint with ruff and mypy
make all       # Run format + lint
```

### Testing
```bash
make test                           # Run all tests
uv run pytest tests/unit            # Run unit tests only
uv run pytest tests/integration     # Run integration tests only
uv run pytest tests/unit/test_utils.py  # Run specific test file
uv run pytest -k test_name          # Run specific test by name
```

### Building and Publishing
```bash
uv build                                    # Build package (creates dist/)
twine upload --repository pypi dist/*       # Upload to PyPI
make clean                                  # Clean build artifacts
```

## Architecture

### Core Structure

The codebase follows a layered architecture with clear separation of concerns:

```
src/kguru/
├── config/          # Configuration management
├── core/
│   └── reasoning/
│       ├── llm/     # LLM provider implementations
│       └── rules/   # Reasoning rules (planned)
├── star/            # STAR framework implementation (planned)
└── utils/           # Reusable utilities
```

### LLM Provider Architecture

**Pattern**: Abstract base class with provider-specific implementations

The LLM system is built around an abstract `BaseLLM` class (`core/reasoning/llm/base.py`) that defines a consistent async API:

- `reason(**kwargs) -> str` - Generate text responses
- `reason_structure(**kwargs) -> dict` - Generate structured JSON responses
- `stream(**kwargs) -> AsyncGenerator[str]` - Stream response chunks

**Current Providers**:
- `OpenAILLM` (`openai.py`) - OpenAI API with support for reasoning models (o1, o1-mini)
- `AzureOpenAILLM` (`azure.py`) - Azure OpenAI with deployment-specific configuration

### Type Hints
- Use modern Python 3.12+ type syntax: `dict[str, Any]` not `Dict[str, Any]`
- Always use type hints and type checking.
- Use `from collections.abc import AsyncGenerator` not `typing.AsyncGenerator`
- Use `str | None` not `Optional[str]`

### Testing
- Tests are split into `tests/unit/` and `tests/integration/`
- Use pytest with async support (`pytest-asyncio`)
- Configuration in `pyproject.toml` under `[tool.pytest.ini_options]`

## Package Information

- **Build System**: Hatchling (src-layout in `src/`)
- **Python Version**: >=3.12
- **Dependencies**: openai, loguru, python-dotenv
- **Dev Tools**: ruff (formatting/linting), mypy (type checking), pre-commit
- **Status**: Alpha (v0.1.0)

## Repository Management

- Uses `uv` for dependency management and package building
- Pre-commit hooks configured for ruff and standard checks
- PyPI publishing via twine with token authentication

## Development Guidelines
- Always use type hints and type checking.
- Make function small and focused on single responsibility.
- Follow SOLID and KISS principles.
