@ia-ccun/code-agent-cli 0.0.52-release → 0.0.53-beta.1

package/config/agent/skills/chroma/chroma-local/error-handling/python.md

@@ -0,0 +1,166 @@
+---
+name: Error Handling
+description: Handling errors and failures when working with Chroma
+---
+
+## Error Handling
+
+Local Chroma operations can fail for various reasons: the local server may not be running, collections may be missing, or input data may be invalid. This guide covers the common local error scenarios and how to handle them.
+
+```python
+import json
+import time
+
+import chromadb
+from chromadb.errors import NotFoundError
+from chromadb.types import Metadata
+```
+
+### Error types
+
+**Python** uses specific exception classes:
+- `chromadb.errors.NotFoundError` - Collection, tenant, or database doesn't exist
+- `ValueError` - Invalid collection name or duplicate creation attempt
+
+**TypeScript** throws standard `Error` objects with descriptive messages. Check the error message to determine the cause.
+
+### Connection errors
+
+Connection failures occur when the client can't reach the Chroma server. This is common during startup or when network issues occur.
+
+```python
+def connect_with_retry(max_retries: int = 3):
+    """Connect to a local Chroma server with exponential backoff retry."""
+    client = chromadb.HttpClient(host="localhost", port=8000)
+
+    for attempt in range(1, max_retries + 1):
+        try:
+            client.heartbeat()
+            return client
+        except Exception as e:
+            if attempt == max_retries:
+                raise ConnectionError(
+                    f"Failed to connect to local Chroma after {max_retries} attempts: {e}"
+                )
+
+            time.sleep(2 ** (attempt - 1))
+
+    raise ConnectionError("Chroma is unreachable")
+```
+
+### Collection not found
+
+When working with collections that may not exist, handle the `NotFoundError` (Python) or catch the error and check its message (TypeScript).
+
+```python
+client = chromadb.HttpClient(host="localhost", port=8000)
+
+try:
+    collection = client.get_collection(name="my_collection")
+except NotFoundError:
+    print("Collection not found, creating it...")
+    collection = client.create_collection(name="my_collection")
+```
+
+### Safe collection access pattern
+
+The `getOrCreateCollection` method is the recommended way to avoid "not found" errors entirely. Use `getCollection` only when you specifically need to verify a collection exists.
+
+```python
+client = chromadb.HttpClient(host="localhost", port=8000)
+collection = client.get_or_create_collection(name="my_collection")
+
+results = collection.query(
+    query_texts=["search query"],
+    n_results=5,
+)
+
+if results["documents"] and len(results["documents"][0]) > 0:
+    first_doc = results["documents"][0][0]
+else:
+    pass
+```
+
+### Validation errors
+
+Chroma validates data before operations. Common validation failures include:
+- Document content exceeding 16KB
+- Embedding dimensions not matching the collection
+- Metadata exceeding limits (4KB total, 32 keys max)
+- Invalid collection names
+
+```python
+client = chromadb.HttpClient(host="localhost", port=8000)
+
+
+def validate_document(doc: str) -> bool:
+    byte_size = len(doc.encode("utf-8"))
+    return byte_size <= 16384
+
+
+def validate_metadata(metadata: Metadata) -> bool:
+    if len(metadata.keys()) > 32:
+        return False
+
+    json_size = len(json.dumps(metadata).encode("utf-8"))
+    return json_size <= 4096
+
+
+def safe_add(
+    collection_name: str,
+    ids: list[str],
+    documents: list[str],
+    metadatas: list[Metadata] | None
+) -> None:
+    for doc in documents:
+        if not validate_document(doc):
+            raise ValueError("Document exceeds 16KB limit")
+
+    if metadatas:
+        for meta in metadatas:
+            if not validate_metadata(meta):
+                raise ValueError("Metadata exceeds limits (4KB or 32 keys)")
+
+    collection = client.get_or_create_collection(name=collection_name)
+    collection.add(ids=ids, documents=documents, metadatas=metadatas)
+```
+
+### Batch operation failures
+
+When adding or upserting multiple documents, a single invalid document fails the entire batch. Validate data before sending, or implement retry logic for partial failures.
+
+```python
+client = chromadb.HttpClient(host="localhost", port=8000)
+
+
+def batch_add(
+    collection_name: str,
+    ids: list[str],
+    documents: list[str],
+    batch_size: int = 100,
+) -> dict:
+    collection = client.get_or_create_collection(name=collection_name)
+    failures = []
+
+    for i in range(0, len(ids), batch_size):
+        batch_ids = ids[i : i + batch_size]
+        batch_docs = documents[i : i + batch_size]
+
+        try:
+            collection.add(ids=batch_ids, documents=batch_docs)
+        except Exception as e:
+            failures.append({"index": i, "error": str(e)})
+
+    total_batches = (len(ids) + batch_size - 1) // batch_size
+    return {"total_batches": total_batches, "failures": failures}
+```
+
+### Defensive patterns summary
+
+| Scenario | Recommended approach |
+|----------|---------------------|
+| Collection access | Use `getOrCreateCollection` instead of `getCollection` |
+| Missing data | Check results length before accessing |
+| Connection issues | Implement retry with exponential backoff |
+| Large batches | Validate data size before operations |
+| Local server startup | Verify the server is running before debugging query logic |

package/config/agent/skills/chroma/chroma-local/error-handling/typescript.md

@@ -0,0 +1,231 @@
+---
+name: Error Handling
+description: Handling errors and failures when working with Chroma
+---
+
+## Error Handling
+
+Local Chroma operations can fail for various reasons: the local server may not be running, collections may be missing, or input data may be invalid. This guide covers the common local error scenarios and how to handle them.
+
+```typescript
+import { ChromaClient } from 'chromadb';
+import { DefaultEmbeddingFunction } from '@chroma-core/default-embed';
+```
+
+### Error types
+
+**Python** uses specific exception classes:
+- `chromadb.errors.NotFoundError` - Collection, tenant, or database doesn't exist
+- `ValueError` - Invalid collection name or duplicate creation attempt
+
+**TypeScript** throws standard `Error` objects with descriptive messages. Check the error message to determine the cause.
+
+### Connection errors
+
+Connection failures occur when the client can't reach the Chroma server. This is common during startup or when network issues occur.
+
+```typescript
+async function connectWithRetry(maxRetries = 3): Promise<ChromaClient> {
+  const client = new ChromaClient();
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      // heartbeat() verifies the connection is working
+      await client.heartbeat();
+      return client;
+    } catch (error) {
+      if (attempt === maxRetries) {
+        throw new Error(
+          `Failed to connect to Chroma after ${maxRetries} attempts: ${error}`
+        );
+      }
+      // Exponential backoff: 1s, 2s, 4s...
+      const delay = Math.pow(2, attempt - 1) * 1000;
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+  throw new Error('Unreachable');
+}
+```
+
+### Collection not found
+
+When working with collections that may not exist, handle the `NotFoundError` (Python) or catch the error and check its message (TypeScript).
+
+```typescript
+const client = new ChromaClient();
+const embeddingFunction = new DefaultEmbeddingFunction();
+
+// getCollection throws if the collection doesn't exist
+try {
+  const collection = await client.getCollection({
+    name: 'my_collection',
+    embeddingFunction,
+  });
+} catch (error) {
+  if (error instanceof Error && error.message.includes('does not exist')) {
+    console.log('Collection not found, creating it...');
+    // Handle missing collection
+  } else {
+    throw error; // Re-throw unexpected errors
+  }
+}
+```
+
+### Safe collection access pattern
+
+The `getOrCreateCollection` method is the recommended way to avoid "not found" errors entirely. Use `getCollection` only when you specifically need to verify a collection exists.
+
+```typescript
+const client2 = new ChromaClient();
+const embeddingFunction2 = new DefaultEmbeddingFunction();
+
+// Preferred: getOrCreateCollection never throws "not found"
+const collection = await client2.getOrCreateCollection({
+  name: 'my_collection',
+  embeddingFunction: embeddingFunction2,
+});
+
+// Check if results exist before accessing
+const results = await collection.query({
+  queryTexts: ['search query'],
+  nResults: 5,
+});
+
+if (results.documents[0] && results.documents[0].length > 0) {
+  const firstDoc = results.documents[0][0];
+  // Safe to use firstDoc
+} else {
+  // No results found
+}
+```
+
+### Validation errors
+
+Chroma validates data before operations. Common validation failures include:
+- Document content exceeding 16KB
+- Embedding dimensions not matching the collection
+- Metadata exceeding limits (4KB total, 32 keys max)
+- Invalid collection names
+
+```typescript
+const client3 = new ChromaClient();
+const embeddingFunction3 = new DefaultEmbeddingFunction();
+
+// Validate document size before adding (16KB limit, recommend < 8KB)
+function validateDocument(doc: string): boolean {
+  const byteSize = new TextEncoder().encode(doc).length;
+  return byteSize <= 16384;
+}
+
+// Validate metadata size (4KB limit, 32 keys max)
+function validateMetadata(
+  metadata: Record<string, string | number | boolean>
+): boolean {
+  const keys = Object.keys(metadata);
+  if (keys.length > 32) return false;
+
+  const jsonSize = new TextEncoder().encode(JSON.stringify(metadata)).length;
+  return jsonSize <= 4096;
+}
+
+async function safeAdd(
+  collectionName: string,
+  ids: string[],
+  documents: string[],
+  metadatas?: Record<string, string | number | boolean>[]
+) {
+  // Pre-validate
+  for (const doc of documents) {
+    if (!validateDocument(doc)) {
+      throw new Error(`Document exceeds 16KB limit`);
+    }
+  }
+
+  if (metadatas) {
+    for (const meta of metadatas) {
+      if (!validateMetadata(meta)) {
+        throw new Error(`Metadata exceeds limits (4KB or 32 keys)`);
+      }
+    }
+  }
+
+  const collection = await client3.getOrCreateCollection({
+    name: collectionName,
+    embeddingFunction: embeddingFunction3,
+  });
+
+  try {
+    await collection.add({ ids, documents, metadatas });
+  } catch (error) {
+    // Handle specific validation errors from server
+    if (error instanceof Error) {
+      if (error.message.includes('dimension')) {
+        throw new Error('Embedding dimensions do not match collection');
+      }
+      if (error.message.includes('duplicate')) {
+        throw new Error('Duplicate IDs in batch');
+      }
+    }
+    throw error;
+  }
+}
+```
+
+### Batch operation failures
+
+When adding or upserting multiple documents, a single invalid document fails the entire batch. Validate data before sending, or implement retry logic for partial failures.
+
+```typescript
+const client4 = new ChromaClient();
+const embeddingFunction4 = new DefaultEmbeddingFunction();
+
+// Process documents in batches to avoid memory issues and partial failures
+async function batchAdd(
+  collectionName: string,
+  ids: string[],
+  documents: string[],
+  batchSize = 100
+) {
+  const collection = await client4.getOrCreateCollection({
+    name: collectionName,
+    embeddingFunction: embeddingFunction4,
+  });
+
+  const failures: { index: number; error: string }[] = [];
+
+  for (let i = 0; i < ids.length; i += batchSize) {
+    const batchIds = ids.slice(i, i + batchSize);
+    const batchDocs = documents.slice(i, i + batchSize);
+
+    try {
+      await collection.add({
+        ids: batchIds,
+        documents: batchDocs,
+      });
+    } catch (error) {
+      // Log failure but continue with other batches
+      failures.push({
+        index: i,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  if (failures.length > 0) {
+    console.error(`${failures.length} batches failed:`, failures);
+  }
+
+  return { totalBatches: Math.ceil(ids.length / batchSize), failures };
+}
+```
+
+### Defensive patterns summary
+
+| Scenario | Recommended approach |
+|----------|---------------------|
+| Collection access | Use `getOrCreateCollection` instead of `getCollection` |
+| Missing data | Check results length before accessing |
+| Connection issues | Implement retry with exponential backoff |
+| Large batches | Validate data size before operations |
+| Local server startup | Verify the server is running before debugging query logic |

package/config/agent/skills/chroma/chroma-local/local-chroma/python.md

@@ -0,0 +1,95 @@
+---
+name: Local Chroma
+description: How to run and use local chroma
+---
+
+## Local Chroma
+
+Running Chroma locally is useful for development, testing, and production applications where data privacy or offline operation is important. Local Chroma stores data on disk and runs as a separate process that your application connects to over HTTP.
+
+### When to use local vs cloud
+
+**Use local Chroma when:**
+- Developing and testing before deploying to production
+- Data must stay on-premises for compliance or privacy reasons
+- You need offline operation without network dependencies
+- Running integration tests in CI/CD pipelines
+
+**Use Chroma Cloud when:**
+- You need the Schema() and Search() APIs for advanced indexing
+- You want managed infrastructure without operational overhead
+- You need hybrid search with SPLADE or other cloud-only features
+- Scaling beyond what a single machine can handle
+
+### Installation
+
+For Python, install with pip or uv:
+
+```
+pip install chromadb
+# or
+uv pip install chromadb
+```
+
+To start the Chroma server from a Python environment:
+
+```
+chroma run
+```
+
+By default, this starts Chroma on `localhost:8000` and persists data to a local directory.
+
+For JavaScript/TypeScript, install with npm:
+
+```
+npm install chromadb
+```
+
+To start the Chroma server:
+
+```
+npx chroma run
+```
+
+### Connecting to local Chroma
+
+```python
+import chromadb
+```
+
+Once the server is running, connect using the `ChromaClient` (not `CloudClient`):
+
+```python
+chroma_client = chromadb.HttpClient(host='localhost', port=8000)
+
+# this will automaically use the default embedding function
+collection = chroma_client.get_or_create_collection(name="my_collection")
+
+collection.add(
+    ids=["id1", "id2"],
+    documents=[
+        "This is a document about pineapple",
+        "This is a document about oranges"
+    ]
+)
+
+results = collection.query(
+    query_texts=["This is a query document about hawaii"], # Chroma will embed this for you
+    n_results=2 # how many results to return
+)
+print(results)
+```
+
+### Persistence
+
+Local Chroma persists data to disk automatically. By default, data is stored in `.chroma/` in the current directory. You can specify a different path when starting the server:
+
+```
+chroma run --path /path/to/data
+```
+
+This makes it safe to restart the server without losing your indexed documents.
+
+### Further reading
+
+For full the full configuration of the chroma server, see: https://docs.trychroma.com/reference/server-env-vars

package/config/agent/skills/chroma/chroma-local/local-chroma/typescript.md

@@ -0,0 +1,101 @@
+---
+name: Local Chroma
+description: How to run and use local chroma
+---
+
+## Local Chroma
+
+Running Chroma locally is useful for development, testing, and production applications where data privacy or offline operation is important. Local Chroma stores data on disk and runs as a separate process that your application connects to over HTTP.
+
+### When to use local vs cloud
+
+**Use local Chroma when:**
+- Developing and testing before deploying to production
+- Data must stay on-premises for compliance or privacy reasons
+- You need offline operation without network dependencies
+- Running integration tests in CI/CD pipelines
+
+**Use Chroma Cloud when:**
+- You need the Schema() and Search() APIs for advanced indexing
+- You want managed infrastructure without operational overhead
+- You need hybrid search with SPLADE or other cloud-only features
+- Scaling beyond what a single machine can handle
+
+### Installation
+
+For Python, install with pip or uv:
+
+```
+pip install chromadb
+# or
+uv pip install chromadb
+```
+
+To start the Chroma server from a Python environment:
+
+```
+chroma run
+```
+
+By default, this starts Chroma on `localhost:8000` and persists data to a local directory.
+
+For JavaScript/TypeScript, install with npm:
+
+```
+npm install chromadb
+```
+
+To start the Chroma server:
+
+```
+npx chroma run
+```
+
+### Connecting to local Chroma
+
+```typescript
+import { ChromaClient } from 'chromadb';
+import { DefaultEmbeddingFunction } from '@chroma-core/default-embed';
+```
+
+Once the server is running, connect using the `ChromaClient` (not `CloudClient`):
+
+```typescript
+// client with no args uses local chroma instance
+const client = new ChromaClient();
+
+const embeddingFunction = new DefaultEmbeddingFunction();
+
+const collection = await client.getOrCreateCollection({
+  name: 'my_collection',
+  embeddingFunction,
+});
+
+await collection.add({
+  ids: ['doc1', 'doc2'],
+  documents: [
+    'Apples are really good red fruit',
+    'Red cars tend to get more speeding tickets',
+  ],
+});
+
+const results = await collection.query({
+  queryTexts: ['I like red apples'],
+});
+
+const firstResult = results.documents[0];
+```
+
+### Persistence
+
+Local Chroma persists data to disk automatically. By default, data is stored in `.chroma/` in the current directory. You can specify a different path when starting the server:
+
+```
+chroma run --path /path/to/data
+```
+
+This makes it safe to restart the server without losing your indexed documents.
+
+### Further reading
+
+For full the full configuration of the chroma server, see: https://docs.trychroma.com/reference/server-env-vars