Query Agent Doc Rework

.gitignore

@@ -274,3 +274,5 @@ tests/backups/
 
 # Ignore LLM/agent config files
 .claude/
+
+docs/agents old/*

docs/agents/_includes/code/additional_filters.mts

@@ -0,0 +1,85 @@
+import 'dotenv/config'
+import weaviate from 'weaviate-client';
+const { loadClientInternally, populateWeaviate } = await import('./util.mjs').catch(() => import('../docs/agents/_includes/code/util.mjs'));
+const client = await loadClientInternally();
+await populateWeaviate(client, false);
+
+const weatherCollection = client.collections.use('Weather');
+const financialCollection = client.collections.use('FinancialContracts');
+const ecommerceCollection = client.collections.use('ECommerce');
+
+// START OverviewInInit
+import { QueryAgent } from 'weaviate-agents';
+
+const qa = new QueryAgent(client, {
+    collections: [
+        {
+            name: 'Weather',
+            additionalFilters: weatherCollection.filter.byProperty('temperature').greaterThan(10),
+        },
+    ],
+});
+// END OverviewInInit
+
+// START OverviewInRuntime
+const runtimeConfig = {
+    name: 'Weather',
+    additionalFilters: weatherCollection.filter.byProperty('humidity').equal(39),
+};
+
+const response = await qa.ask("Provide a summary of the weather patterns", {
+    collections: [runtimeConfig],
+});
+// END OverviewInRuntime
+
+// START FilterExampleBad
+const badResponse = await qa.ask(
+    `What type of contracts have been signed and who were the authors? 
+    IMPORTANT: Only look at contracts from 2025.`,
+    {
+        collections: ['FinancialContracts'],
+    }
+);
+// END FilterExampleBad
+
+
+// START FilterExampleGood
+import { Filters } from 'weaviate-client';
+const goodResponse = await qa.ask(
+    `What products were sold last month?`,
+    {
+        collections: [
+            {
+                name: 'FinancialContracts',
+                additionalFilters: Filters.and(
+                    financialCollection.filter.byProperty('date').greaterThan(new Date(2025, 0, 1)),
+                    financialCollection.filter.byProperty('date').lessThan(new Date(2026, 0, 1)),
+                ),
+            },
+        ],
+    }
+);
+// END FilterExampleGood
+
+// START BasicFilter
+const basicFilterConfig = {
+    name: 'ECommerce',
+    additionalFilters: ecommerceCollection.filter.byProperty('category').equal('Tops'),
+};
+// END BasicFilter
+
+
+// START NestedFilter
+const nestedFilterConfig = {
+    name: 'ECommerce',
+    additionalFilters: Filters.or(
+        ecommerceCollection.filter.byProperty('category').equal('Shoes'),
+        Filters.and(
+            ecommerceCollection.filter.byProperty('price').greaterThan(50),
+            ecommerceCollection.filter.byProperty('price').lessThan(100),
+        ),
+    ),
+};
+// END NestedFilter
+
+await client.close();

docs/agents/_includes/code/additional_filters.py

@@ -0,0 +1,98 @@
+import sys
+sys.path.insert(0, "docs/agents/_includes/code")
+from util import load_client_internally, populate_weaviate
+client = load_client_internally()
+populate_weaviate(client, False)
+
+# START OverviewInInit
+from weaviate.agents.query import QueryAgent
+from weaviate.agents.classes import QueryAgentCollectionConfig
+from weaviate.classes.query import Filter
+
+qa = QueryAgent(
+    client=client,
+    collections=[
+        QueryAgentCollectionConfig(
+            name="Weather",
+            additional_filters=Filter.by_property("temperature").greater_than(10)
+        ),
+    ],
+    # END OverviewInInit
+    timeout=120,
+    # START OverviewInInit
+)
+# END OverviewInInit
+
+# START OverviewInRuntime
+runtime_config = QueryAgentCollectionConfig(
+    name="Weather",
+    additional_filters=Filter.by_property("humidity").equal(39)
+)
+
+response = qa.ask(
+    query="Provide a summary of the weather patterns", 
+    collections=[runtime_config]
+)
+# END OverviewInRuntime
+
+# START FilterExampleBad
+response = qa.ask(
+    query=(
+        "What type of contracts have been signed and who were the authors?"
+        "IMPORTANT: Only look at contracts from 2025."
+    ),
+    collections=["FinancialContracts"]
+)
+# END FilterExampleBad
+
+
+# START FilterExampleGood
+from datetime import datetime, timezone
+
+start_date = datetime(2025, 1, 1, tzinfo=timezone.utc)
+end_date = datetime(2026, 1, 1, tzinfo=timezone.utc)
+
+response = qa.ask(
+    query="What type of contracts have been signed and who were the authors?",
+    collections=[
+        QueryAgentCollectionConfig(
+            name="FinancialContracts",
+            additional_filters=(
+                Filter.all_of(
+                    [
+                        Filter.by_property("date").greater_than(start_date),
+                        Filter.by_property("date").less_than(end_date)
+                    ]
+                )
+            )
+        )
+    ]
+)
+# END FilterExampleGood
+
+# START BasicFilter
+QueryAgentCollectionConfig(
+    name="ECommerce",
+    additional_filters=Filter.by_property("category").equal("Tops")
+)
+# END BasicFilter
+
+
+# START NestedFilter
+QueryAgentCollectionConfig(
+    name="ECommerce",
+    additional_filters=Filter.any_of(
+        [
+            Filter.by_property("category").equal("Shoes"),
+            Filter.all_of(
+                [
+                    Filter.by_property("price").greater_than(50),
+                    Filter.by_property("price").less_than(100)
+                ]
+            )
+        ]
+    )
+)
+# END NestedFilter
+
+client.close()

docs/agents/_includes/code/advanced_collections.mts

@@ -0,0 +1,50 @@
+const { loadClientInternally, populateWeaviate } = await import('./util.mjs').catch(() => import('../docs/agents/_includes/code/util.mjs'));
+const client = await loadClientInternally();
+await populateWeaviate(client, false);
+
+// START SimpleConfig
+import { QueryAgent } from 'weaviate-agents';
+
+const qaSimple = new QueryAgent(client, {
+    collections: ['ECommerce', 'FinancialContracts'],
+});
+// END SimpleConfig
+
+// START AdvancedConfig
+const qa = new QueryAgent(client, {
+    collections: [
+        // Provide an object to specify further collection configuration
+        {
+            name: 'ECommerce',
+            targetVector: [
+                'name_description_brand_vector'
+            ],
+            viewProperties: [
+                'name',
+                'description',
+                'category',
+                'brand',
+            ],
+        },
+        {
+            name: 'FinancialContracts'
+        },
+    ],
+});
+// END AdvancedConfig
+
+// START RuntimeConfigAsk
+const response = await qa.ask(
+    "Recommend some shoes below $60.", {
+    collections: [
+        {
+            name: 'ECommerce',
+            targetVector: [
+                'name_description_brand_vector'
+            ],
+        }
+    ],
+});
+// END RuntimeConfigAsk
+
+await client.close()

docs/agents/_includes/code/advanced_collections.py

@@ -0,0 +1,63 @@
+import sys
+sys.path.insert(0, "docs/agents/_includes/code")
+from util import load_client_internally, populate_weaviate
+
+client = load_client_internally()
+populate_weaviate(client, False)
+
+from weaviate.agents.query import QueryAgent
+from weaviate.agents.classes import QueryAgentCollectionConfig
+
+
+# START SimpleConfig
+from weaviate.agents.query import QueryAgent
+
+qa = QueryAgent(
+    client=client,
+    collections=["ECommerce", "FinancialContracts"],
+)
+# END SimpleConfig
+
+# START AdvancedConfig
+from weaviate.agents.classes import QueryAgentCollectionConfig
+
+qa = QueryAgent(
+    client=client,
+    collections=[
+        # Use QueryAgentCollectionConfig class to provide further collection configuration
+        QueryAgentCollectionConfig(
+            name="ECommerce", 
+            target_vector=[
+                "name_description_brand_vector"
+            ], 
+            view_properties=[
+                "name",
+                "description",
+                "category",
+                "brand",
+            ],  
+        ),
+        QueryAgentCollectionConfig(
+            name="FinancialContracts"
+        ),
+    ],
+)
+
+# END AdvancedConfig
+
+
+# START RuntimeConfigAsk
+response = qa.ask(
+    "Recommend some shoes below $60.",
+    collections=[
+        QueryAgentCollectionConfig(
+            name="ECommerce",
+            target_vector=[
+                "name_description_brand_vector"
+            ],
+        ),
+    ],
+)
+# END RuntimeConfigAsk
+
+client.close()

docs/agents/_includes/code/ask_mode.mts

@@ -0,0 +1,67 @@
+import 'dotenv/config'
+const { populateWeaviate } = await import('./util.mjs').catch(() => import('../docs/agents/_includes/code/util.mjs'));
+
+
+// START BasicAskMode
+import weaviate, { WeaviateClient, vectors, dataType, configure } from 'weaviate-client';
+import { QueryAgent } from 'weaviate-agents';
+
+// END BasicAskMode
+
+// START ImportAskResponse
+import { AskModeResponse } from 'weaviate-agents';
+// END ImportAskResponse
+
+// START StreamingExample
+import { ProgressMessage, StreamedTokens } from 'weaviate-agents';
+// END StreamingExample
+
+// START BasicAskMode
+const client = await weaviate.connectToWeaviateCloud(
+    process.env.WEAVIATE_URL as string, {
+    authCredentials: new weaviate.ApiKey(process.env.WEAVIATE_API_KEY as string),
+});
+
+const qa = new QueryAgent(client, {
+    collections: ['Weather'],
+    systemPrompt:
+        "You are a helpful assistant. " +
+        "Write your response in short, 5 word sentences. " +
+        "Emphasize key insights."
+});
+
+// END BasicAskMode
+
+await populateWeaviate(client, false);
+
+// START BasicAskMode
+const res = await qa.ask("What was the average temperature in the first week of May 2025?", {
+    resultEvaluation: "none",
+});
+
+// END BasicAskMode
+
+// START StreamingAskMode
+for await (const output of qa.askStream("What was the average temperature in the first week of May 2025?")) {
+    // Do something with the output
+}
+// END StreamingAskMode
+
+// START StreamingExample
+function printStreamOutput(output: ProgressMessage | StreamedTokens | AskModeResponse) {
+    if (output.outputType === "progressMessage") {
+        console.log(output.message);
+    } else if (output.outputType === "streamedTokens") {
+        process.stdout.write(output.delta);
+    } else {
+        output.display();
+    }
+}
+
+for await (const output of qa.askStream("What was the average temperature in the first week of May 2025?")) {
+    printStreamOutput(output);
+}
+
+// END StreamingExample
+
+await client.close();