llm-connect/.claude/rules/stack-and-commands.md

## Stack

- **Language:** Python 3.10+
- **Key deps (runtime):** `toml` (TOML config parsing)
- **Key deps (dev):** `pytest`, `ruff`, `mypy`
- **HTTP:** stdlib `urllib` via `_http.py` (no requests/httpx runtime dep)
- **Build:** setuptools / uv

## Dev Commands

```bash
# Install (editable, with dev extras)
uv pip install -e ".[dev]"
# or
pip install -e ".[dev]"

# Run tests
uv run pytest
# or
pytest

# Lint
uv run ruff check .

# Type check
uv run mypy llm_connect

# Run a single test file
uv run pytest tests/test_models.py -v

# Build package (dry run)
uv build --no-sources
```

## Project layout

```
llm_connect/         source package
  adapter.py         LLMAdapter ABC + Mock/ErrorLLMAdapter
  models.py          RunConfig, LLMResponse
  exceptions.py      LLMError hierarchy
  factory.py         create_adapter()
  openai.py          OpenAIAdapter
  gemini.py          GeminiAdapter
  openrouter.py      OpenRouterAdapter
  claude_code.py     ClaudeCodeAdapter
  embedding_adapter.py  EmbeddingAdapter ABC
  embedding_openai.py   OpenAICompatibleEmbeddingAdapter
  embedding_cache.py    EmbeddingCache
  embedding_factory.py  create_embedding_adapter()
  toml_config.py     7-level TOML config resolution
  config.py          LLMConfig, resolve_api_key, find_project_root
  _http.py           shared HTTP POST utility
  _token_estimator.py  rough token count estimate
  similarity.py      cosine similarity utilities
tests/               pytest test suite
contracts/           GAAF-2026 contract docs
workplans/           workplan files (LLM-WP-NNNN)
```