# Repository Guidelines

## Project Structure & Module Organization

This is an async Rust SDK for the Ollama API. The crate name is `ollama-api-rs` but it is imported as `oai_sdk`.

- `src/` — Core source code
  - `lib.rs` — Crate root and public exports
  - `client.rs` — HTTP client and builder
  - `chat.rs` — Chat completion endpoints
  - `generate.rs` — Text generation endpoints
  - `embed.rs` — Embeddings endpoints
  - `model.rs` — Model management endpoints
  - `error.rs` — Error types and handling
- `tests/` — Test suite
  - `mock_tests.rs` — Mocked HTTP tests with `wiremock`
  - `integration_test.rs` — Integration tests against a live instance
  - `e2e_test.rs` — End-to-end tests (ignored by default)
- `examples/` — Runnable examples: `basic_chat.rs`, `streaming_chat.rs`, `embeddings.rs`, `model_management.rs`, `tool_calling.rs`

## Build, Test, and Development Commands

| Command | Purpose |
|---|---|
| `cargo check` | Fast compile check |
| `cargo build` | Build all targets |
| `cargo test` | Run unit, integration, and mock tests |
| `cargo test --test mock_tests` | Run only mocked tests |
| `cargo test --test e2e_test -- --ignored` | Run E2E tests against a real Ollama instance |
| `cargo run --example basic_chat` | Run an example |
| `cargo doc --open` | Build and open local documentation |

Feature flags:
- `stream` — Enable streaming response support
- `rustls` — Use `rustls-tls` instead of default TLS
- `local` — Minimal dependency set for local usage

## Coding Style & Naming Conventions

- Follow **Rust Edition 2024** idioms.
- Use `rustfmt` and `clippy` with default settings; no custom configuration is provided.
- Indent with 4 spaces (standard Rust).
- Naming: `PascalCase` for types and traits, `snake_case` for functions, variables, and modules. `SCREAMING_SNAKE_CASE` for constants.
- Import ordering: std, external crates, then crate-internal modules.
- Every source file must include the Apache 2.0 license header.

## Testing Guidelines

- Use `tokio::test` for all async tests.
- Mocked tests live in `tests/mock_tests.rs` and use `wiremock` to simulate the Ollama API.
- E2E tests live in `tests/e2e_test.rs` and are marked `#[ignore]`; they require a running Ollama instance at `http://localhost:11434`.
- Keep tests deterministic; do not rely on external network state in non-E2E tests.

## Commit & Pull Request Guidelines

- Write commit messages in **Conventional Commits** format:
  - `feat:` — New feature
  - `fix:` — Bug fix
  - `refactor:` — Code restructuring
  - `docs:` — Documentation only
  - `test:` — Test additions or changes
- Keep commits atomic and focused on a single change.
- Pull requests should include a short description of what changed and why. Link any related issues.
- Ensure `cargo test` passes and `cargo clippy` reports no warnings before submitting.

## Agent-Specific Instructions

- Always use the **worktree** skill.
- Always use the **rust best practices** skill.
- You are not allowed to use destructive git operations or any other operation that destroys files unless instructed specifically. Always ask for permission before proceeding.
- When editing code, match the existing module structure. Do not create monolithic files.
- Do not introduce new dependencies without explicit approval.
- Do not modify or remove the Apache 2.0 license headers.
- Do not use placeholders, TODOs, or stub implementations.
