Add an admin client for dataset management (#17)

* *: Add dependencies and model generation for admin client

- Add pydantic>=2.0,<2.12 for data models (constrained for PyIceberg)
- Add datamodel-code-generator for model generation from OpenAPI
- Add respx for HTTP mocking in tests
- Add Makefile target for regenerating models
- Generate 838 lines of Pydantic v2 models from OpenAPI spec
- Add test manifest files for dataset registration testing

* admin: Implement admin client infrastructure

- Create AdminClient base class with HTTP request handling and
error mapping
- Implement DatasetsClient with register/deploy/list/delete operations
- Implement JobsClient with get/list/wait/stop/delete operations
- Implement SchemaClient for SQL validation and schema inference
- Create DeploymentContext for chainable deployment workflows
- Add exception hierarchy with 30+ typed error classes mapped from
API codes
- Support automatic job polling with configurable timeout

* client: Integrate admin client with unified Client class

- Add query_url and admin_url parameters to Client (backward compatible
with url)
- Add datasets, jobs, schema properties for admin operations
- Extend QueryBuilder with with_dependency() for manifest dependencies
- Add to_manifest() for generating dataset manifests from SQL queries
- Add register_as() for one-line registration returning DeploymentContext
- Support fluent API: query → with_dependency → register_as → deploy
- Maintain backward compatibility (existing Client(url=...) still works)

* tests: Add admin client tests

- Add 10 unit tests for error mapping and exception hierarchy
- Add 10 unit tests for Pydantic model validation
- Add 10 integration tests for AdminClient HTTP operations
- Add 10 integration tests for DatasetsClient operations
- Add 18 integration tests for JobsClient operations including polling
- All 48 tests use respx for HTTP mocking (no real server required)
- 0.65s execution time on dev machine

* docs: Update README with admin client features

- Add admin client to feature list
- Add quick start examples for admin operations
- Add links to admin client guide and API reference
- Update overview to highlight dataset management capabilities

* docs: Add admin client documentation and examples

- Add comprehensive admin_client_guide.md with usage patterns and
best practices
- Add complete API reference in docs/api/admin_api.md

Author: fordN

Makefile

@@ -1,5 +1,5 @@
 SHELL := /bin/bash
-.PHONY: test test-unit test-integration test-all clean setup lint format
+.PHONY: test test-unit test-integration test-all clean setup lint format generate-models
 
 # Use UV for all commands
 PYTHON = uv run --env-file .test.env
@@ -59,10 +59,19 @@ lint:
 	@echo "🔍 Linting code..."
 	$(PYTHON) ruff check .
 
+lint-fix:
+	@echo "🔍 Linting code..."
+	$(PYTHON) ruff check . --fix
+
 format:
 	@echo "✨ Formatting code..."
 	$(PYTHON) ruff format .
 
+# Generate Pydantic models from OpenAPI spec
+generate-models:
+	@echo "🏗️  Generating Pydantic models from OpenAPI spec..."
+	$(PYTHON) python scripts/generate_models.py
+
 # Setup development environment
 setup:
 	@echo "🚀 Setting up development environment..."
@@ -115,6 +124,7 @@ clean:
 help:
 	@echo "Available commands:"
 	@echo "  make setup                    - Setup development environment"
+	@echo "  make generate-models          - Generate Pydantic models from OpenAPI spec"
 	@echo "  make test-unit                - Run unit tests (fast)"
 	@echo "  make test-integration         - Run integration tests"
 	@echo "  make test-parallel-streaming  - Run parallel streaming integration tests"

README.md

@@ -5,9 +5,16 @@
 [![Formatting status](https://github.com/edgeandnode/amp-python/actions/workflows/ruff.yml/badge.svg?event=push)](https://github.com/edgeandnode/amp-python/actions/workflows/ruff.yml)
 
 
-## Overview 
+## Overview
 
-Client for issuing queries to an Amp server and working with the returned data.
+Python client for Amp - a high-performance data infrastructure for blockchain data.
+
+**Features:**
+- **Query Client**: Issue Flight SQL queries to Amp servers
+- **Admin Client**: Manage datasets, deployments, and jobs programmatically
+- **Data Loaders**: Zero-copy loading into PostgreSQL, Redis, Snowflake, Delta Lake, Iceberg, and more
+- **Parallel Streaming**: High-throughput parallel data ingestion with automatic resume
+- **Manifest Generation**: Fluent API for creating and deploying datasets from SQL queries
 
 ## Installation
 
@@ -21,7 +28,57 @@ Client for issuing queries to an Amp server and working with the returned data.
     uv venv
    ```
 
-## Useage 
+## Quick Start
+
+### Querying Data
+
+```python
+from amp import Client
+
+# Connect to Amp server
+client = Client(url="grpc://localhost:8815")
+
+# Execute query and convert to pandas
+df = client.query("SELECT * FROM eth.blocks LIMIT 10").to_pandas()
+print(df)
+```
+
+### Admin Operations
+
+```python
+from amp import Client
+
+# Connect with admin capabilities
+client = Client(
+    query_url="grpc://localhost:8815",
+    admin_url="http://localhost:8080",
+    auth_token="your-token"
+)
+
+# Register and deploy a dataset
+job = (
+    client.query("SELECT block_num, hash FROM eth.blocks")
+    .with_dependency('eth', '_/[email protected]')
+    .register_as('_', 'my_dataset', '1.0.0', 'blocks', 'mainnet')
+    .deploy(parallelism=4, end_block='latest', wait=True)
+)
+
+print(f"Deployment completed: {job.status}")
+```
+
+### Loading Data
+
+```python
+# Load query results into PostgreSQL
+loader = client.query("SELECT * FROM eth.blocks").load(
+    loader_type='postgresql',
+    connection='my_pg_connection',
+    table_name='eth_blocks'
+)
+print(f"Loaded {loader.rows_written} rows")
+```
+
+## Usage
 
 ### Marimo
 
@@ -30,19 +87,23 @@ Start up a marimo workspace editor
 uv run marimo edit
 ```
 
-The Marimo app will open a new browser tab where you can create a new notebook, view helpful resources, and 
+The Marimo app will open a new browser tab where you can create a new notebook, view helpful resources, and
 browse existing notebooks in the workspace.
 
 ### Apps
 
-You can execute python apps and scripts using `uv run <path>` which will give them access to the dependencies 
+You can execute python apps and scripts using `uv run <path>` which will give them access to the dependencies
 and the `amp` package. For example, you can run the `execute_query` app with the following command.
 ```bash
 uv run apps/execute_query.py
 ```
 
 ## Documentation
 
+### Getting Started
+- **[Admin Client Guide](docs/admin_client_guide.md)** - Complete guide for dataset management and deployment
+- **[Admin API Reference](docs/api/admin_api.md)** - Full API documentation for admin operations
+
 ### Features
 - **[Parallel Streaming Usage Guide](docs/parallel_streaming_usage.md)** - User guide for high-throughput parallel data loading
 - **[Parallel Streaming Design](docs/parallel_streaming.md)** - Technical design documentation for parallel streaming architecture