feat: add comprehensive live API testing and contributing documentation

CONTRIBUTING.md

@@ -0,0 +1,204 @@
+# Contributing to genai
+
+Thank you for your interest in contributing to genai! This document provides guidelines and information for contributors.
+
+## Development Setup
+
+### Prerequisites
+
+- Rust (latest stable version)
+- Git
+
+### Setup Steps
+
+1. Fork the repository
+2. Clone your fork locally
+3. Create a new branch for your feature or bugfix
+4. Make your changes
+5. Run tests and ensure code quality
+6. Submit a pull request
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+cargo test
+
+# Run tests with output
+cargo test -- --nocapture
+
+# Run specific test file
+cargo test --test live_api_tests
+```
+
+### Live API Testing
+
+genai includes comprehensive live API tests that validate functionality against real AI providers. These tests are located in `/tests/live_api_tests.rs`.
+
+#### **IMPORTANT: Live API Tests Require Real Credentials**
+
+The live API tests make actual API calls to providers like OpenRouter and Anthropic. To run these tests:
+
+1. **Set API Keys as Environment Variables:**
+
+```bash
+export OPENROUTER_API_KEY="your-openrouter-api-key"
+export ANTHROPIC_API_KEY="your-anthropic-api-key"
+# Optional: Cerebras
+export CEREBRAS_API_KEY="your-cerebras-api-key"
+```
+
+2. **Run the Live API Tests:**
+
+```bash
+cargo test --test live_api_tests -- --nocapture
+```
+
+#### **Available Live API Tests**
+
+The test suite includes comprehensive validation of:
+
+- ✅ **Basic Chat Functionality** - Tests basic chat completion
+- ✅ **Streaming Support** - Validates real-time streaming responses
+- ✅ **Tool/Function Calling** - Tests function calling capabilities
+- ✅ **JSON Mode** - Validates structured JSON output
+- ✅ **Image Processing** - Tests image analysis functionality
+- ✅ **Multiple Providers** - Cross-provider compatibility testing
+- ✅ **Error Handling** - Validates proper error scenarios
+- ✅ **Model Resolution** - Tests model name resolution
+
+#### **Test Structure**
+
+- **Enabled Tests**: Core functionality tests are enabled by default
+- **Ignored Tests**: Some tests are marked with `#[ignore]` to avoid excessive API calls during development
+- **Environment Checks**: Tests automatically skip if required API keys are not set
+
+#### **Adding New Live API Tests**
+
+When adding new live API tests:
+
+1. Follow the existing patterns in `/tests/live_api_tests.rs`
+2. Include environment variable checks for required API keys
+3. Use the `TestResult` type for consistent error handling
+4. Add appropriate assertions and logging
+5. Consider marking expensive tests with `#[ignore]`
+
+Example test structure:
+
+```rust
+#[tokio::test]
+async fn test_new_feature() -> TestResult<()> {
+    if !has_env_key("PROVIDER_API_KEY") {
+        println!("Skipping PROVIDER_API_KEY not set");
+        return Ok(());
+    }
+
+    let client = Client::default();
+    let chat_req = ChatRequest::new(vec![
+        ChatMessage::user("Test message"),
+    ]);
+
+    let result = client.exec_chat("model-name", chat_req, None).await?;
+    let content = result.first_text().ok_or("Should have content")?;
+
+    assert!(!content.is_empty(), "Content should not be empty");
+    println!("✅ Test passed: {}", content);
+
+    Ok(())
+}
+```
+
+## Code Quality
+
+### Formatting
+
+```bash
+# Check formatting
+cargo fmt --check
+
+# Apply formatting
+cargo fmt
+```
+
+### Linting
+
+```bash
+# Run clippy with strict warnings
+cargo clippy --all-targets --all-features -- -W clippy::all
+
+# Run clippy with default settings
+cargo clippy --all-targets --all-features
+```
+
+### Code Style Guidelines
+
+- Follow Rust idioms and conventions
+- Use meaningful variable and function names
+- Add documentation for public APIs
+- Keep functions focused and small
+- Handle errors appropriately
+
+## Provider-Specific Testing
+
+### Model Names
+
+When testing with specific providers, ensure model names are current and available:
+
+- **OpenRouter**: Use namespaced models (e.g., `openrouter::anthropic/claude-3.5-sonnet`)
+- **Anthropic**: Use current model names (e.g., `claude-3-5-sonnet-20241022`)
+- **Other Providers**: Check provider documentation for latest model names
+
+### API Key Management
+
+- Never commit API keys to the repository
+- Use environment variables for API keys
+- Document required environment variables in test files
+- Consider using `.env` files for local development (add to `.gitignore`)
+
+## Submitting Changes
+
+### Pull Request Process
+
+1. Ensure all tests pass
+2. Run code formatting and linting
+3. Update documentation if needed
+4. Write clear commit messages
+5. Submit pull request with descriptive title and description
+
+### Commit Message Format
+
+```
+feat: add new feature description
+fix: resolve issue description
+docs: update documentation
+test: add or improve tests
+refactor: code refactoring
+```
+
+## Getting Help
+
+- Check existing issues and pull requests
+- Review the codebase and examples
+- Ask questions in pull requests
+- Refer to provider documentation for API-specific details
+
+## Provider Documentation
+
+When working with specific AI providers, refer to their official documentation:
+
+- [OpenRouter API](https://openrouter.ai/docs)
+- [Anthropic API](https://docs.anthropic.com)
+- [OpenAI API](https://platform.openai.com/docs)
+- [Google Gemini API](https://ai.google.dev/docs)
+- [Other Providers](https://github.com/jeremychone/rust-genai#provider-mapping)
+
+## Security Considerations
+
+- Never expose API keys in code or commits
+- Validate and sanitize user inputs when appropriate
+- Follow security best practices for API integrations
+- Report security vulnerabilities privately
+
+Thank you for contributing to genai! 🚀

README.md

@@ -241,8 +241,18 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 - Add the Google Vertex AI variants.
 - May add the Azure OpenAI variant (not sure yet).
 
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on:
+
+- Development setup
+- Running tests (including live API tests)
+- Code quality standards
+- Submitting changes
+
 ## Links
 
 - crates.io: [crates.io/crates/genai](https://crates.io/crates/genai)
 - GitHub: [github.com/jeremychone/rust-genai](https://github.com/jeremychone/rust-genai)
+- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
 - Sponsored by [BriteSnow](https://britesnow.com) (Jeremy Chone's consulting company)

tests/anthropic_test_plan.md

@@ -0,0 +1,66 @@
+# Anthropic Platform Rust Test Plan
+
+This plan translates the requirements into executable Rust test suites for the genai library. Each section maps the Anthropic Platform surface area to concrete `cargo test` targets, identifies fixtures/mocks, and calls out validation checkpoints (headers, payload schemas, streaming, and error handling).
+
+## Core Messages API
+- `POST /v1/messages` happy path (non-streaming): validate required headers (`x-api-key`, `anthropic-version`), response schema, usage token accounting.
+- Streaming variant: drive `ChatRequest::stream = Some(true)` through the genai handler, assert SSE framing and final message assembly.
+- Tool calling: include `tools` and `tool_choice`, confirm tool outputs are echoed.
+- Multimodal messages: include `ContentBlock::Image` and ensure payload normalization.
+- Error handling: simulate invalid model, missing parameters, and propagate `ProxyError`.
+
+## Token Counting
+- `POST /v1/messages/count_tokens` round-trip against Anthropic mock server verifying `input_tokens` field alignment with `TokenCounter`.
+- Boundary cases: empty conversation, maximum context window (200k), cache-control system prompts.
+
+## Message Batches
+- Submission (`POST /v1/messages/batches`): validate batch envelope, custom IDs, and metadata propagation.
+- Polling endpoints: `GET /v1/messages/batches/{batch_id}` and `/results` using paginated fixtures to ensure deserialization and continuation token handling.
+- Cancellation and deletion flows: exercise `cancel` (with optional reason) and `DELETE` endpoints, assert status transitions `in_progress → canceled`.
+
+## Files API
+- Upload (`POST /v1/files`): multipart builder helper, ensure boundary formatting and metadata passthrough.
+- Listing (`GET /v1/files`): pagination tests with `has_more` toggles.
+- Metadata retrieval and download: confirm binary streaming and content-type preservation.
+- Deletion: verify 204 response and idempotent behaviour.
+
+## Models API
+- Catalog (`GET /v1/models`): deserialize pricing/context metadata, compare against routing configuration expectations.
+- Single model lookup (`GET /v1/models/{model_id}`): assert alias resolution and capability flags (tool support, context window).
+
+## Experimental Prompt Tools
+- `POST /v1/experimental/generate_prompt`: ensure optional beta headers are injected and response structures match spec.
+
+## Cross-Cutting Scenarios
+- Header contract: reusable assertion helper to check Anthropic diagnostic headers (`request-id`, `anthropic-organization-id`) on every response.
+- Timeout/resiliency: simulate transient network failures with `RetryExecutor`, assert retry backoff and logging.
+- Intelligent routing integration: run end-to-end tests where Anthropic is selected via markdown-driven routing and verify request transformation layers.
+
+## Implementation Notes
+- Use `#[cfg(feature = "anthropic-live")]` gated tests for real API calls; default suite relies on mocks.
+- Provide fixture builders in `tests/support/anthropic.rs` to keep test setup concise.
+- Record golden JSON payloads in `tests/data/anthropic/` for snapshot comparisons.
+- Update CI pipeline matrix to run `cargo test --features anthropic-live` nightly with sanitized secrets.
+
+## Additional Test Areas for genai
+
+### Reasoning Models
+- Test Claude thinking models with reasoning budget
+- Validate reasoning usage reporting
+- Test reasoning effort parameters
+
+### Caching
+- Explicit cache control headers
+- Implicit caching behavior
+- Cache hit/miss validation
+
+### Vision/Multimodal
+- Image URL support
+- Base64 image encoding
+- PDF document processing
+- Multi-modal message handling
+
+### Rate Limiting
+- Header-based rate limit detection
+- Retry-after header handling
+- Concurrent request limits