v2: Define package structure for v2 API

[oss-amikos]

Context

PR #80 went back and forth between a flat package (tech.amikos.chromadb.v2.*) and an organized one (v2.client, v2.model, v2.auth). We need to decide the final structure before writing code.

Proposed Structure

tech.amikos.chromadb/
├── Client.java                     // Client interface
├── ChromaClient.java               // Public: builder + factory methods
├── Collection.java                 // Collection interface
├── CreateCollectionOptions.java    // Public options
├── ListCollectionsOptions.java
├── Where.java                      // Filter DSL
├── WhereDocument.java
├── Include.java                    // Enum
├── DistanceFunction.java           // Enum
├── Tenant.java                     // Value object
├── Database.java                   // Value object
├── CollectionConfiguration.java    // Value object
│
├── QueryResult.java                // Result interface
├── GetResult.java                  // Result interface
│
├── ChromaException.java            // Exception hierarchy
├── ChromaClientException.java
├── ChromaNotFoundException.java
├── ChromaServerException.java
├── ChromaConnectionException.java
├── ... (other exceptions)
│
├── auth/
│   ├── AuthProvider.java           // Interface
│   ├── TokenAuth.java
│   ├── BasicAuth.java
│   └── ChromaTokenAuth.java
│
└── internal/                       // Package-private, not part of public API
    ├── HttpTransport.java
    ├── ChromaHttpCollection.java
    ├── CollectionModel.java        // JSON deserialization model
    ├── QueryResponseModel.java
    ├── GetResponseModel.java
    └── ... (other internal models)

Design Decisions

1. Drop the v2 sub-package — this IS the new version of the library. Version is in the Maven artifact version, not the package name. Import path: tech.amikos.chromadb.Client, not tech.amikos.chromadb.v2.Client.

2. Public API in root package — everything users import is in tech.amikos.chromadb. Maximum discoverability.

3. auth/ sub-package — auth providers are a clear sub-domain. Users import tech.amikos.chromadb.auth.BasicAuth.

4. internal/ sub-package — HTTP transport, JSON models, implementation details. Package-private classes. Convention: anything in internal is not part of the public API contract.

5. No model/ sub-package — value objects (Tenant, Database, etc.) live in the root package alongside the interfaces that use them. Keeps imports clean.

Alternative: Keep v2 sub-package

If we want v1 and v2 to coexist in the same JAR:

tech.amikos.chromadb/         // v1 (existing, deprecated)
tech.amikos.chromadb.v2/      // v2 (new)

Recommendation: Don't do this. Cut a clean 0.2.0 release. Users who need v1 stay on 0.1.x.

Acceptance Criteria

• Package structure agreed upon
• All new v2 classes created in the correct packages
• No public classes in internal/ package
• Clean import experience for users

Blocks

• All implementation issues (v2: Implement HTTP transport layer — replace swagger-generated code #88, v2: Implement ChromaClient (Client interface) — collection CRUD, tenant/database ops #89, v2: Implement Collection record operations — add, query, get, update, upsert, delete #90)