@ia-ccun/code-agent-cli 0.0.52-beta.6 → 0.0.52-beta.8

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

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

@@ -0,0 +1,154 @@
+---
+name: Metadata
+description: Store and query metadata, including filters and array values
+---
+
+## Metadata
+
+Metadata in Chroma is structured key-value data stored alongside each document. You can use metadata to filter records in both `query` and `get`, and the metadata model is the same between local and cloud.
+
+### Imports and boilerplate
+
+```python
+import chromadb
+
+client = chromadb.HttpClient(host="localhost", port=8000)
+```
+
+### Filtering with `where`
+
+The `where` argument filters documents by metadata. With `query`, this reduces the candidate set before similarity search runs. The same filter syntax also works with `get` when you want metadata-based retrieval without similarity ranking.
+
+```python
+collection = client.get_or_create_collection(name="articles")
+
+query_results = collection.query(
+    query_texts=["interest rates outlook"],
+    where={
+        "category": "research",
+    },
+)
+
+filtered_docs = collection.get(
+    where={
+        "$and": [
+            {"year": {"$gte": 2025}},
+            {"region": {"$in": ["us", "eu"]}},
+        ]
+    },
+    limit=20,
+)
+
+direct_filter = {
+    "metadata_field": "search_string",
+}
+
+explicit_filter = {
+    "metadata_field": {
+        "$eq": "search_string",
+    }
+}
+```
+
+### Available filter operators
+
+Chroma supports these operators in `where` clauses:
+
+- **Equality:** `$eq` (default if just a value), `$ne`
+- **Comparison:** `$gt`, `$gte`, `$lt`, `$lte`
+- **Set membership:** `$in`, `$nin`
+- **Array:** `$contains`, `$not_contains`
+- **Logical:** `$and`, `$or`
+
+Filters can be nested and combined for complex queries. Filtering in Chroma is usually better than retrieving a larger result set and post-processing it in application code.
+
+### Storing arrays in metadata
+
+Chroma supports storing arrays of strings, numbers, and booleans in metadata fields. This removes the need for workarounds like comma-separated strings or JSON serialization when one field needs multiple values.
+
+**Rules:**
+- All elements in an array must share the same type
+- Arrays are stored directly on metadata fields alongside regular scalar values
+
+```python
+collection.add(
+    ids=["article-1", "article-2", "article-3"],
+    documents=[
+        "Net interest income rose 12% in Q3",
+        "New lending products launched in Southeast Asia",
+        "Central bank holds rates steady amid inflation concerns",
+    ],
+    metadatas=[
+        {
+            "topics": ["net-interest-income", "earnings", "quarterly-results"],
+            "year": 2026,
+        },
+        {
+            "topics": ["lending", "expansion", "southeast-asia"],
+            "year": 2026,
+        },
+        {
+            "topics": ["rates", "central-bank", "inflation"],
+            "year": 2026,
+        },
+    ],
+)
+```
+
+### Querying array metadata with `$contains`
+
+Use `$contains` in a `where` filter to find records where an array metadata field includes a specific value.
+
+```python
+results = collection.query(
+    query_texts=["lending products"],
+    where={
+        "topics": {"$contains": "lending"},
+    },
+)
+```
+
+### Querying array metadata with `$not_contains`
+
+Use `$not_contains` to exclude records where an array metadata field includes a specific value.
+
+```python
+filtered = collection.query(
+    query_texts=["economic outlook"],
+    where={
+        "topics": {"$not_contains": "inflation"},
+    },
+)
+```
+
+### Combining array and scalar filters
+
+Array filters compose with existing logical operators (`$and`, `$or`) and can be combined with scalar metadata filters in the same query.
+
+```python
+combined = collection.query(
+    query_texts=["financial results"],
+    where={
+        "$and": [
+            {"topics": {"$contains": "earnings"}},
+            {"year": {"$gte": 2025}},
+        ]
+    },
+)
+
+multi_match = collection.query(
+    query_texts=["market trends"],
+    where={
+        "$or": [
+            {"topics": {"$contains": "rates"}},
+            {"topics": {"$contains": "inflation"}},
+        ]
+    },
+)
+```
+
+### Common use cases
+
+- **Multi-label tagging:** Store tags or categories as arrays, then filter with `$contains` to find matching records without joins or separate tables.
+- **Access control:** Store allowed roles or groups as an array, then filter by the current user's role at query time.
+- **Tenant and source filtering:** Store fields like tenant ID, source system, or document type so retrieval can stay scoped to the relevant subset.