@ia-ccun/code-agent-cli 0.0.52 → 0.0.53

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.

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