feat: Add auto-launch functionality for local Meilisearch instances

.gitignore

@@ -147,3 +147,8 @@ dmypy.json
 html/
 
 .vscode
+
+# Meilisearch
+data.ms/
+*.ms
+meili_data/

CLAUDE.md

@@ -0,0 +1,197 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 🏗️ Project Overview
+
+This is the **Meilisearch Python SDK** - the official Python client library for the Meilisearch search engine. It provides a complete Python interface for all Meilisearch API operations including document management, search, index configuration, and administrative tasks.
+
+## 🚀 Development Commands
+
+### Environment Setup
+```bash
+# Install dependencies
+pipenv install --dev
+
+# Activate virtual environment
+pipenv shell
+```
+
+### Testing
+```bash
+# Start Meilisearch server (required for tests)
+curl -L https://install.meilisearch.com | sh
+./meilisearch --master-key=masterKey --no-analytics
+
+# Run all tests
+pipenv run pytest tests
+
+# Run tests with coverage
+pipenv run pytest tests --cov=meilisearch --cov-report term-missing
+
+# Run specific test file
+pipenv run pytest tests/client/test_client.py
+
+# Run with Docker (alternative)
+docker pull getmeili/meilisearch:latest
+docker run -p 7700:7700 getmeili/meilisearch:latest meilisearch --master-key=masterKey --no-analytics
+```
+
+### Code Quality
+```bash
+# Type checking
+pipenv run mypy meilisearch
+
+# Linting
+pipenv run pylint meilisearch tests
+
+# Code formatting
+pipenv run black meilisearch tests
+pipenv run isort meilisearch tests
+```
+
+### Testing All Python Versions
+```bash
+# Using tox (runs tests on all supported Python versions)
+pipenv run tox
+```
+
+### Docker Development
+```bash
+# Run all checks with docker
+docker-compose run --rm package bash -c "pipenv install --dev && pipenv run mypy meilisearch && pipenv run pylint meilisearch tests && pipenv run pytest tests"
+```
+
+## 🏛️ Architecture Overview
+
+### Core Structure
+- **`meilisearch/client.py`**: Main `Client` class - entry point for all API operations
+- **`meilisearch/index.py`**: `Index` class - handles index-specific operations (search, documents, settings)
+- **`meilisearch/task.py`**: Task management and waiting utilities
+- **`meilisearch/_httprequests.py`**: HTTP request handling and error management
+- **`meilisearch/models/`**: Pydantic models for API responses and configuration
+
+### API Client Pattern
+The SDK follows a hierarchical client pattern:
+```python
+# Client -> Index -> Operations
+client = meilisearch.Client('http://localhost:7700', 'masterKey')
+index = client.index('movies')
+results = index.search('query')
+```
+
+### Key Design Patterns
+1. **Async Task Handling**: Most write operations return tasks that can be waited for
+2. **Type Safety**: Full typing with mypy strict mode enabled
+3. **Error Hierarchy**: Custom exceptions in `meilisearch/errors.py`
+4. **HTTP Abstraction**: Centralized HTTP handling with automatic retries and error conversion
+5. **Model Validation**: Pydantic models for request/response validation
+
+### Testing Strategy
+- **Integration Tests**: Most tests run against real Meilisearch instance
+- **Fixtures**: Automatic index cleanup between tests via `conftest.py`
+- **Test Environment**: Uses `tests/common.py` for shared configuration
+- **Coverage**: Tests cover client operations, index management, search, settings, and error handling
+
+## 🔧 Development Guidelines
+
+### Code Style
+- **Black**: Line length 100, Python 3.8+ target
+- **isort**: Black-compatible import sorting
+- **mypy**: Strict type checking enabled
+- **pylint**: Custom configuration in `pyproject.toml`
+
+### Testing Requirements
+- Must have running Meilisearch server on `http://127.0.0.1:7700` with master key `masterKey`
+- Tests automatically clean up indexes after each run
+- Use `pytest` for all test execution
+- Coverage reports required for new features
+
+### Error Handling
+- All API errors convert to `MeilisearchApiError` with structured error information
+- HTTP errors handled in `_httprequests.py`
+- Timeout and communication errors have specific exception types
+
+### Type Hints
+- All public methods must have complete type annotations
+- Use `from __future__ import annotations` for forward references
+- Models use Pydantic for runtime validation
+
+## 📦 SDK Architecture
+
+### Client Hierarchy
+```
+Client (meilisearch/client.py)
+├── Index management (create, list, delete indexes)
+├── Global operations (health, version, stats, keys, tasks)
+├── Multi-search functionality
+└── Index (meilisearch/index.py)
+    ├── Document operations (add, update, delete, get)
+    ├── Search operations (search, facet_search)
+    ├── Settings management (all index configuration)
+    └── Task operations (wait_for_task, get_tasks)
+```
+
+### Models Structure
+- **`models/document.py`**: Document and search result models
+- **`models/index.py`**: Index settings and statistics models  
+- **`models/key.py`**: API key management models
+- **`models/task.py`**: Task status and batch operation models
+- **`models/embedders.py`**: AI embedder configuration models
+
+### HTTP Layer
+- `_httprequests.py` handles all HTTP communication
+- Automatic JSON serialization/deserialization
+- Custom serializer support for complex types (datetime, UUID)
+- Centralized error handling and retry logic
+
+## 🧪 Test Organization
+
+### Test Structure
+```
+tests/
+├── client/          # Client-level operations
+├── index/           # Index-specific operations  
+├── settings/        # Index settings tests
+├── models/          # Model validation tests
+├── errors/          # Error handling tests
+└── conftest.py      # Shared fixtures and cleanup
+```
+
+### Key Test Patterns
+- Each test module focuses on specific functionality
+- Tests use real Meilisearch server for integration testing
+- Automatic cleanup ensures test isolation
+- Tests verify both success and error cases
+
+## 🔍 Common Development Tasks
+
+### Adding New API Endpoints
+1. Add method to appropriate class (`Client` for global, `Index` for index-specific)
+2. Add type hints for parameters and return values
+3. Add corresponding model classes if needed
+4. Write integration tests covering success and error cases
+5. Update documentation if it's a public feature
+
+### Running Single Test Categories
+```bash
+# Test specific functionality
+pipenv run pytest tests/client/          # Client operations
+pipenv run pytest tests/index/           # Index operations  
+pipenv run pytest tests/settings/        # Settings management
+pipenv run pytest tests/models/          # Model validation
+```
+
+### Debugging
+```python
+import pdb
+pdb.set_trace()  # Add breakpoint for debugging
+```
+
+## 📝 Release Process
+
+Version management:
+- Version defined in `meilisearch/version.py`
+- Semantic versioning (MAJOR.MINOR.PATCH)
+- Automated via GitHub Actions workflow
+- Publishes to PyPI automatically on release

CONTRIBUTING.md

@@ -47,10 +47,15 @@ Each PR should pass the tests, mypy type checking, and the linter to be accepted
 Your PR also needs to be formatted using black and isort.
 
 ```bash
-# Tests
+# Tests (Option 1 - Auto-launch)
+# The SDK will automatically download and launch Meilisearch if needed
+pipenv run pytest tests
+
+# Tests (Option 2 - Manual setup)
 curl -L https://install.meilisearch.com | sh # download Meilisearch
 ./meilisearch --master-key=masterKey --no-analytics # run Meilisearch
 pipenv run pytest tests
+
 # MyPy
 pipenv run mypy meilisearch
 # Linter

README.md

@@ -42,7 +42,7 @@ To learn more about Meilisearch Python, refer to the in-depth [Meilisearch Pytho
 
 ## 🔧 Installation
 
-**Note**: Python 3.8+ is required.
+**Note**: Python 3.9+ is required.
 
 With `pip3` in command line:
 
@@ -52,9 +52,19 @@ pip3 install meilisearch
 
 ### Run Meilisearch <!-- omit in toc -->
 
-⚡️ **Launch, scale, and streamline in minutes with Meilisearch Cloud**—no maintenance, no commitment, cancel anytime. [Try it free now](https://cloud.meilisearch.com/login?utm_campaign=oss&utm_source=github&utm_medium=meilisearch-python).
+There are three ways to use Meilisearch:
 
-🪨  Prefer to self-host? [Download and deploy](https://www.meilisearch.com/docs/learn/self_hosted/getting_started_with_self_hosted_meilisearch?utm_campaign=oss&utm_source=github&utm_medium=meilisearch-python) our fast, open-source search engine on your own infrastructure.
+1. **🆕 Auto-Launch (Easiest)**: Let the Python client automatically download and run Meilisearch for you:
+```python
+import meilisearch
+
+# No URL needed - Meilisearch will be automatically launched!
+client = meilisearch.Client()
+```
+
+2. **☁️ Meilisearch Cloud**: Launch, scale, and streamline in minutes—no maintenance, no commitment, cancel anytime. [Try it free now](https://cloud.meilisearch.com/login?utm_campaign=oss&utm_source=github&utm_medium=meilisearch-python).
+
+3. **🪨 Self-Host**: [Download and deploy](https://www.meilisearch.com/docs/learn/self_hosted/getting_started_with_self_hosted_meilisearch?utm_campaign=oss&utm_source=github&utm_medium=meilisearch-python) our fast, open-source search engine on your own infrastructure.
 
 ## 🚀 Getting started
 
@@ -63,7 +73,11 @@ pip3 install meilisearch
 ```python
 import meilisearch
 
-client = meilisearch.Client('http://127.0.0.1:7700', 'masterKey')
+# Automatic launch - no setup required!
+client = meilisearch.Client()
+
+# Or connect to an existing instance
+# client = meilisearch.Client('http://127.0.0.1:7700', 'masterKey')
 
 # An index is where the documents are stored.
 index = client.index('movies')
@@ -234,6 +248,44 @@ index.search(
 }
 ```
 
+### Auto-Launch Feature <!-- omit in toc -->
+
+The Python SDK can automatically launch a local Meilisearch instance for you, making development even easier:
+
+```python
+import meilisearch
+
+# No URL needed - Meilisearch will be automatically launched!
+client = meilisearch.Client()
+
+# Use it like normal
+index = client.index('products')
+index.add_documents([{"id": 1, "name": "Laptop"}])
+
+# The server will be automatically stopped when the client is destroyed
+```
+
+You can also use it with a context manager for automatic cleanup:
+
+```python
+with meilisearch.Client() as client:
+    # Meilisearch is running
+    client.index('products').add_documents([{"id": 1, "name": "Laptop"}])
+# Meilisearch is automatically stopped here
+```
+
+With a custom master key:
+
+```python
+client = meilisearch.Client(api_key='myMasterKey')
+```
+
+**Note**: The auto-launch feature will:
+- Check if Meilisearch is installed in your PATH
+- If not found, automatically download the latest version for your platform
+- Store the binary in `~/.meilisearch/bin/`
+- Create temporary data directories that are cleaned up on exit
+
 ## 🤖 Compatibility with Meilisearch
 
 This package guarantees compatibility with [version v1.2 and above of Meilisearch](https://github.com/meilisearch/meilisearch/releases/latest), but some features may not be present. Please check the [issues](https://github.com/meilisearch/meilisearch-python/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+label%3Aenhancement) for more info.