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

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

@@ -0,0 +1,153 @@
+---
+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
+
+```typescript
+import { ChromaClient } from 'chromadb';
+import { DefaultEmbeddingFunction } from '@chroma-core/default-embed';
+
+const client = new ChromaClient();
+const embeddingFunction = new DefaultEmbeddingFunction();
+```
+
+### 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.
+
+```typescript
+const collection = await client.getOrCreateCollection({
+  name: 'articles',
+  embeddingFunction,
+});
+
+const queryResults = await collection.query({
+  queryTexts: ['interest rates outlook'],
+  where: {
+    category: 'research',
+  },
+});
+
+const filteredDocs = await collection.get({
+  where: {
+    $and: [{ year: { $gte: 2025 } }, { region: { $in: ['us', 'eu'] } }],
+  },
+  limit: 20,
+});
+
+const directFilter = {
+  metadata_field: 'search_string',
+};
+
+const explicitFilter = {
+  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
+
+```typescript
+await 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.
+
+```typescript
+const results = await collection.query({
+  queryTexts: ['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.
+
+```typescript
+const filtered = await collection.query({
+  queryTexts: ['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.
+
+```typescript
+const combined = await collection.query({
+  queryTexts: ['financial results'],
+  where: {
+    $and: [{ topics: { $contains: 'earnings' } }, { year: { $gte: 2025 } }],
+  },
+});
+
+const multiMatch = await collection.query({
+  queryTexts: ['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.

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

@@ -0,0 +1,147 @@
+---
+name: Query and Get
+description: Query and Get Data from Chroma Collections
+---
+
+## Querying
+
+Chroma provides two main methods for retrieving documents: `query` and `get`. Understanding when to use each is important for building effective search.
+
+### Query vs Get
+
+**Use `query` when:**
+- You have a search query (text that needs to be embedded and compared)
+- You want results ranked by semantic similarity
+- Building search features, RAG systems, or recommendation engines
+
+**Use `get` when:**
+- You know the exact document IDs you want
+- You need to retrieve documents by metadata without similarity ranking
+- Fetching documents to display after a search, or for batch operations
+
+### Imports and boilerplate
+
+```python
+from typing import Optional, TypedDict
+
+import chromadb
+
+client = chromadb.HttpClient(host="localhost", port=8000)
+```
+
+### Basic query
+
+The `query` method embeds your query text and finds the nearest neighbors in the collection. Results are returned in order of similarity.
+
+```python
+collection = client.get_or_create_collection(name="my_collection")
+
+collection.add(
+    ids=["doc1", "doc2"],
+    documents=[
+        "Apples are really good red fruit",
+        "Red cars tend to get more speeding tickets",
+    ],
+)
+
+results = collection.query(
+    query_texts=["I like red apples"],
+)
+
+first_result = results["documents"][0]
+```
+
+### Query with options
+
+You can control what data is returned using `include`, and limit results with `nResults`. By default, Chroma returns 10 results.
+
+```python
+collection2 = client.get_or_create_collection(name="my_collection")
+
+results2 = collection2.query(
+    query_texts=["I like red apples"],
+    n_results=2,
+    include=["metadatas", "documents", "embeddings", "distances"],
+    ids=["id1", "id2"],
+    where={"category": "philosophy"},
+    where_document={"$contains": "wikipedia"},
+)
+
+
+class QueryResult(TypedDict):
+    ids: list[list[str]]
+    embeddings: Optional[list[list[list[float]]]]
+    documents: Optional[list[list[str]]]
+    metadatas: Optional[list[list[dict]]]
+    distances: Optional[list[list[float]]]
+
+
+class GetResult(TypedDict):
+    ids: list[str]
+    embeddings: Optional[list[list[float]]]
+    documents: Optional[list[str]]
+    metadatas: Optional[list[dict]]
+
+
+typed_results: QueryResult = results2
+```
+
+The `include` parameter accepts: `documents`, `metadatas`, `embeddings`, and `distances`. Only request what you need to minimize response size.
+
+### Document content filtering
+
+The `whereDocument` parameter filters on the actual document text, not metadata. This is useful for full-text search within your semantic results.
+
+**Operators:**
+- `$contains` - documents must contain the string (case-sensitive)
+- `$not_contains` - documents must not contain the string
+
+```python
+contains_results = collection.query(
+    query_texts=["search query"],
+    where_document={"$contains": "important keyword"},
+)
+
+excluded_results = collection.query(
+    query_texts=["search query"],
+    where_document={"$not_contains": "deprecated"},
+)
+
+combined_results = collection.query(
+    query_texts=["search query"],
+    where_document={
+        "$and": [
+            {"$contains": "python"},
+            {"$not_contains": "legacy"},
+        ]
+    },
+)
+
+full_filter_results = collection.query(
+    query_texts=["search query"],
+    n_results=10,
+    where={"status": "published"},
+    where_document={"$contains": "tutorial"},
+)
+```
+
+## The `get` method
+
+Use `get` when you need to retrieve documents without similarity ranking. Common use cases:
+
+- Fetching specific documents by ID after a search
+- Paginating through all documents in a collection
+- Retrieving documents by metadata filter only
+
+```python
+docs = collection.get(ids=["doc1", "doc2"])
+
+page = collection.get(limit=20, offset=0)
+
+filtered = collection.get(
+    where={"category": "blog"},
+    limit=50,
+)
+```
+
+The key difference from `query`: `get` returns documents in insertion order (or filtered by metadata), while `query` returns documents ranked by similarity to your query text.

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

@@ -0,0 +1,157 @@
+---
+name: Query and Get
+description: Query and Get Data from Chroma Collections
+---
+
+## Querying
+
+Chroma provides two main methods for retrieving documents: `query` and `get`. Understanding when to use each is important for building effective search.
+
+### Query vs Get
+
+**Use `query` when:**
+- You have a search query (text that needs to be embedded and compared)
+- You want results ranked by semantic similarity
+- Building search features, RAG systems, or recommendation engines
+
+**Use `get` when:**
+- You know the exact document IDs you want
+- You need to retrieve documents by metadata without similarity ranking
+- Fetching documents to display after a search, or for batch operations
+
+### Imports and boilerplate
+
+```typescript
+import { ChromaClient, type IncludeEnum } from 'chromadb';
+import { DefaultEmbeddingFunction } from '@chroma-core/default-embed';
+
+const client = new ChromaClient();
+```
+
+### Basic query
+
+The `query` method embeds your query text and finds the nearest neighbors in the collection. Results are returned in order of similarity.
+
+```typescript
+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];
+```
+
+### Query with options
+
+You can control what data is returned using `include`, and limit results with `nResults`. By default, Chroma returns 10 results.
+
+```typescript
+const embeddingFunction2 = new DefaultEmbeddingFunction();
+
+const collection2 = await client.getOrCreateCollection({
+  name: 'my_collection',
+  embeddingFunction: embeddingFunction2,
+});
+
+const results2 = await collection2.query({
+  queryTexts: ['I like red apples'],
+  nResults: 2,
+  include: ['distances', 'embeddings', 'metadatas'],
+  ids: ['id1', 'id2'],
+  where: { category: 'philosophy' },
+  whereDocument: { $contains: 'wikipedia' },
+});
+
+type QueryResult = {
+  distances: (number | null)[][];
+  documents: (string | null)[][];
+  embeddings: (number[] | null)[][];
+  ids: string[][];
+  include: IncludeEnum[];
+  metadatas: (Record<string, string | number | boolean> | null)[][];
+};
+
+type GetResult = {
+  documents: (string | null)[];
+  embeddings: number[][];
+  ids: string[];
+  include: IncludeEnum[];
+  metadatas: (Record<string, string | number | boolean> | null)[];
+};
+```
+
+The `include` parameter accepts: `documents`, `metadatas`, `embeddings`, and `distances`. Only request what you need to minimize response size.
+
+### Document content filtering
+
+The `whereDocument` parameter filters on the actual document text, not metadata. This is useful for full-text search within your semantic results.
+
+**Operators:**
+- `$contains` - documents must contain the string (case-sensitive)
+- `$not_contains` - documents must not contain the string
+
+```typescript
+const containsResults = await collection.query({
+  queryTexts: ['search query'],
+  whereDocument: { $contains: 'important keyword' },
+});
+
+const excludedResults = await collection.query({
+  queryTexts: ['search query'],
+  whereDocument: { $not_contains: 'deprecated' },
+});
+
+const combinedResults = await collection.query({
+  queryTexts: ['search query'],
+  whereDocument: {
+    $and: [{ $contains: 'python' }, { $not_contains: 'legacy' }],
+  },
+});
+
+const fullFilterResults = await collection.query({
+  queryTexts: ['search query'],
+  nResults: 10,
+  where: { status: 'published' },
+  whereDocument: { $contains: 'tutorial' },
+});
+```
+
+## The `get` method
+
+Use `get` when you need to retrieve documents without similarity ranking. Common use cases:
+
+- Fetching specific documents by ID after a search
+- Paginating through all documents in a collection
+- Retrieving documents by metadata filter only
+
+```typescript
+const docs = await collection.get({
+  ids: ['doc1', 'doc2'],
+});
+
+const page = await collection.get({
+  limit: 20,
+  offset: 0,
+});
+
+const filtered = await collection.get({
+  where: { category: 'blog' },
+  limit: 50,
+});
+```
+
+The key difference from `query`: `get` returns documents in insertion order (or filtered by metadata), while `query` returns documents ranked by similarity to your query text.

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

@@ -0,0 +1,69 @@
+---
+name: Chroma Regex Filtering
+description: Learn how to use regex filters in Chroma queries
+---
+
+## Regex Filtering in Chroma
+
+Chroma supports regex filtering on document content. This is useful when you need exact pattern matching that semantic search can't provide.
+
+### When to use regex vs semantic search
+
+**Use regex when:**
+- Matching exact patterns like email addresses, URLs, or code identifiers
+- Finding documents containing specific formats (dates, phone numbers, IDs)
+- Filtering by prefixes or suffixes in structured data
+- You need deterministic, repeatable matches
+
+**Use semantic search when:**
+- Looking for conceptually similar content regardless of exact wording
+- The user's query is natural language
+- You want to find related content even if it uses different terminology
+
+You can combine both: use regex to narrow results, then rank by semantic similarity.
+
+### Imports and boilerplate
+
+```python
+import chromadb
+
+client = chromadb.HttpClient(host="localhost", port=8000)
+collection = client.get_or_create_collection(name="my_collection")
+```
+
+### Basic Regex Filter
+
+Use the `$regex` operator in `where_document` to match document content against a regular expression. The regex follows standard regex syntax.
+
+```python
+results = collection.query(
+    query_texts=["search query"],
+    where_document={
+        "$regex": "^tech.*"
+    },
+    n_results=10,
+)
+```
+
+### Combining regex with metadata filters
+
+Regex filters can be combined with metadata filters using `$and` and `$or` operators. This is powerful for narrowing results by both content patterns and structured metadata. Note however regex can not be used on metadata string values.
+
+```python
+collection.query(
+    query_texts=["query1", "query2"],
+    where_document={
+        "$and": [
+            {"$contains": "search_string_1"},
+            {"$regex": "[a-z]+"},
+        ]
+    },
+)
+```
+
+### Performance considerations
+
+Regex filtering happens after the initial vector search retrieves candidates. For best performance:
+- Keep regex patterns simple when possible
+- Use metadata filters to reduce the candidate set before regex matching
+- Consider whether a metadata field with pre-extracted values would be faster than runtime regex

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

@@ -0,0 +1,71 @@
+---
+name: Chroma Regex Filtering
+description: Learn how to use regex filters in Chroma queries
+---
+
+## Regex Filtering in Chroma
+
+Chroma supports regex filtering on document content. This is useful when you need exact pattern matching that semantic search can't provide.
+
+### When to use regex vs semantic search
+
+**Use regex when:**
+- Matching exact patterns like email addresses, URLs, or code identifiers
+- Finding documents containing specific formats (dates, phone numbers, IDs)
+- Filtering by prefixes or suffixes in structured data
+- You need deterministic, repeatable matches
+
+**Use semantic search when:**
+- Looking for conceptually similar content regardless of exact wording
+- The user's query is natural language
+- You want to find related content even if it uses different terminology
+
+You can combine both: use regex to narrow results, then rank by semantic similarity.
+
+### Imports and boilerplate
+
+```typescript
+import { DefaultEmbeddingFunction } from '@chroma-core/default-embed';
+import { ChromaClient } from 'chromadb';
+
+const client = new ChromaClient();
+const embedder = new DefaultEmbeddingFunction();
+
+const collection = await client.getOrCreateCollection({
+  name: 'example-collection',
+  embeddingFunction: embedder,
+});
+```
+
+### Basic Regex Filter
+
+Use the `$regex` operator in `where_document` to match document content against a regular expression. The regex follows standard regex syntax.
+
+```typescript
+await collection.query({
+  queryTexts: ['find support tickets with email addresses'],
+  whereDocument: {
+    $regex: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$',
+  },
+});
+```
+
+### Combining regex with metadata filters
+
+Regex filters can be combined with metadata filters using `$and` and `$or` operators. This is powerful for narrowing results by both content patterns and structured metadata. Note however regex can not be used on metadata string values.
+
+```typescript
+await collection.query({
+  queryTexts: ['query1', 'query2'],
+  whereDocument: {
+    $and: [{ $contains: 'search_string_1' }, { $regex: '[a-z]+' }],
+  },
+});
+```
+
+### Performance considerations
+
+Regex filtering happens after the initial vector search retrieves candidates. For best performance:
+- Keep regex patterns simple when possible
+- Use metadata filters to reduce the candidate set before regex matching
+- Consider whether a metadata field with pre-extracted values would be faster than runtime regex

package/config/agent/skills/chroma/chroma-local/understanding-a-codebase.md

@@ -0,0 +1,80 @@
+---
+name: Integrating Chroma into an existing system
+description: Guidance for adding Chroma search to an existing application
+---
+
+## Integrating Chroma into an existing system
+
+Adding search to an existing application requires understanding the data flow and planning both the initial import and ongoing synchronization. This guide helps identify the key questions to answer.
+
+### Key questions to ask the user
+
+Before writing any code, clarify:
+
+1. **What data should be searchable?** (documents, products, messages, etc.)
+2. **Where does that data currently live?** (database, S3, API, files)
+3. **How is the data structured?** (helps determine chunking strategy)
+4. **How often does the data change?** (informs sync strategy)
+5. **What latency is acceptable for updates to appear in search?**
+
+## Understanding the source data
+
+Before designing the import pipeline, ask the user if you can look at a sample of the data that will be made searchable. Seeing real records is far more useful than a description of the schema.
+
+**If the data is in a database:** Write a short script that connects to the database and prints a few records. For example, a script that queries 3-5 rows from the relevant table and prints them to the terminal. This lets you see the actual field names, content lengths, and metadata available.
+
+**If the data is on disk:** Read a few of the files directly to understand their structure, format, and size. For example, if indexing markdown files, read 2-3 of them to see how they're organized.
+
+What to look for:
+- **Which field(s) contain the searchable text** — this becomes the document content in Chroma
+- **How long the content is** — determines whether chunking is needed
+- **What metadata is available** — fields like category, author, date, or tenant ID that could be useful for filtering
+- **How records are identified** — the primary key or filename that will link Chroma documents back to the source
+
+This step prevents guesswork and leads to better chunking and metadata design decisions.
+
+## Initial data import (offline ingest)
+
+The first step is getting existing data into Chroma. This typically involves:
+
+1. **Reading from the source** - database queries, S3 listing, API pagination
+2. **Chunking** - breaking large documents into searchable pieces (see data-model.md)
+3. **Embedding** - converting text chunks to vectors
+4. **Writing to Chroma** - batching for efficiency
+
+Build this as a reusable pipeline, not a one-off script. The same chunking and embedding logic will be needed for ongoing updates.
+
+**Progress tracking:** For large imports, track which records have been processed. This allows resuming after failures and re-running for updates. A simple approach is storing the last processed ID or timestamp.
+
+## Keeping data in sync (online writes)
+
+After the initial import, new and updated data must flow to Chroma. There are two main patterns:
+
+### Asynchronous (recommended)
+
+Use a message queue (SQS, RabbitMQ, Redis streams, etc.) to decouple the primary write path from Chroma updates:
+
+1. Application writes to primary database
+2. Application publishes an event with the record ID
+3. Queue consumer fetches the record, chunks, embeds, and writes to Chroma
+
+**Benefits:** Primary writes aren't slowed by embedding latency. Retries are handled by the queue. Search updates can lag slightly without affecting the main application.
+
+### Synchronous
+
+If no queue infrastructure exists and slight latency is acceptable, update Chroma in the same request:
+
+1. Application writes to primary database
+2. Application chunks, embeds, and writes to Chroma
+3. Request completes
+
+**Tradeoffs:** Simpler infrastructure but adds latency to every write. Failures in Chroma can affect the primary write path unless carefully handled.
+
+**Ask the user:** Do they have an async queue? If not, is synchronous acceptable, or should we set one up?
+
+## Handling updates and deletes
+
+- **Updates:** Re-chunk and re-embed the document, then use `upsert` to replace existing chunks
+- **Deletes:** Delete all chunks for the document by ID prefix or metadata filter
+
+Storing the source record ID in chunk metadata makes this straightforward. For example, if a blog post with ID `post-123` has 3 chunks, store `{"source_id": "post-123", "chunk_index": 0}` etc. on each chunk.