@vfarcic/dot-ai 0.172.0 → 0.174.0

package/README.md

@@ -33,6 +33,7 @@
 DevOps AI Toolkit brings AI-powered intelligence to platform engineering, Kubernetes operations, and development workflows. Built on the Model Context Protocol (MCP), it integrates seamlessly with Claude Code, Cursor, and VS Code.
 
 **Key capabilities:**
+- Natural language cluster querying and exploration
 - Intelligent Kubernetes deployment recommendations
 - AI-powered issue remediation and root cause analysis
 - Organizational pattern and policy management

package/dist/core/base-vector-service.d.ts

@@ -57,6 +57,12 @@ export declare abstract class BaseVectorService<T> {
      * Delete all data (recreate collection)
      */
     deleteAllData(): Promise<void>;
+    /**
+     * Query data with Qdrant filter (no semantic search)
+     * @param filter - Qdrant filter object constructed by AI
+     * @param limit - Maximum results to return
+     */
+    queryWithFilter(filter: any, limit?: number): Promise<T[]>;
     /**
      * Get all data (limited)
      */

package/dist/core/base-vector-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base-vector-service.d.ts","sourceRoot":"","sources":["../../src/core/base-vector-service.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAkB,MAAM,qBAAqB,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEvD,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC;IACR,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;CAC9C;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,8BAAsB,iBAAiB,CAAC,CAAC;IACvC,SAAS,CAAC,QAAQ,EAAE,eAAe,CAAC;IACpC,SAAS,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAC7C,SAAS,CAAC,cAAc,EAAE,MAAM,CAAC;gBAErB,cAAc,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,eAAe,EAAE,gBAAgB,CAAC,EAAE,gBAAgB;IAMnG;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAQjC;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAIrC;;OAEG;IACG,SAAS,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BvC;;OAEG;IACG,UAAU,CACd,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;IAyBjC;;OAEG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAW5C;;OAEG;IACG,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3C;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAIpC;;OAEG;IACG,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAS9C;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAWrC;;OAEG;IACH,aAAa,IAAI,UAAU;IAU3B,SAAS,CAAC,QAAQ,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM;IACpD,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM;IAC7C,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAC9D,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC;IAGjE,SAAS,CAAC,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE;IAIlD;;OAEG;YACW,YAAY;IAkC1B;;OAEG;IACH,OAAO,CAAC,oBAAoB;CA2C7B"}
+{"version":3,"file":"base-vector-service.d.ts","sourceRoot":"","sources":["../../src/core/base-vector-service.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAkB,MAAM,qBAAqB,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEvD,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC;IACR,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;CAC9C;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,8BAAsB,iBAAiB,CAAC,CAAC;IACvC,SAAS,CAAC,QAAQ,EAAE,eAAe,CAAC;IACpC,SAAS,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAC7C,SAAS,CAAC,cAAc,EAAE,MAAM,CAAC;gBAErB,cAAc,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,eAAe,EAAE,gBAAgB,CAAC,EAAE,gBAAgB;IAMnG;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAQjC;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAIrC;;OAEG;IACG,SAAS,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BvC;;OAEG;IACG,UAAU,CACd,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;IAyBjC;;OAEG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAW5C;;OAEG;IACG,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3C;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAIpC;;;;OAIG;IACG,eAAe,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,GAAE,MAAY,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IASrE;;OAEG;IACG,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAS9C;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAWrC;;OAEG;IACH,aAAa,IAAI,UAAU;IAU3B,SAAS,CAAC,QAAQ,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM;IACpD,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM;IAC7C,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAC9D,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC;IAGjE,SAAS,CAAC,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE;IAIlD;;OAEG;YACW,YAAY;IAkC1B;;OAEG;IACH,OAAO,CAAC,oBAAoB;CA2C7B"}

package/dist/core/base-vector-service.js

@@ -118,6 +118,19 @@ class BaseVectorService {
     async deleteAllData() {
         await this.vectorDB.deleteAllDocuments();
     }
+    /**
+     * Query data with Qdrant filter (no semantic search)
+     * @param filter - Qdrant filter object constructed by AI
+     * @param limit - Maximum results to return
+     */
+    async queryWithFilter(filter, limit = 100) {
+        const documents = await this.vectorDB.scrollWithFilter(filter, limit);
+        return documents.map(doc => {
+            const data = this.payloadToData(doc.payload);
+            data.id = doc.id;
+            return data;
+        });
+    }
     /**
      * Get all data (limited)
      */

package/dist/core/capability-tools.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Capability Tools for AI-Powered Cluster Intelligence
+ *
+ * Shared tool definitions and executor for capability vector DB operations.
+ * Used by query, recommend, and other cluster intelligence workflows.
+ *
+ * PRD #291: Cluster Query Tool - Natural Language Cluster Intelligence
+ */
+import { AITool } from './ai-provider.interface';
+/**
+ * Tool: search_capabilities
+ * Semantic search for cluster capabilities by intent/concept
+ */
+export declare const SEARCH_CAPABILITIES_TOOL: AITool;
+/**
+ * Tool: query_capabilities
+ * Filter-based query for capabilities using Qdrant filter syntax
+ */
+export declare const QUERY_CAPABILITIES_TOOL: AITool;
+/**
+ * All capability tools for cluster intelligence
+ * Convenient array for passing to toolLoop()
+ */
+export declare const CAPABILITY_TOOLS: AITool[];
+/**
+ * Tool executor for capability-based tools
+ * Handles execution and error handling for all capability tool calls
+ *
+ * @param toolName - Name of the tool to execute
+ * @param input - Tool input parameters
+ * @returns Tool execution result
+ */
+export declare function executeCapabilityTools(toolName: string, input: any): Promise<any>;
+/**
+ * Reset the capability service (useful for testing)
+ */
+export declare function resetCapabilityService(): void;
+//# sourceMappingURL=capability-tools.d.ts.map

package/dist/core/capability-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-tools.d.ts","sourceRoot":"","sources":["../../src/core/capability-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAGjD;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAwBtC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAkCrC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,EAGpC,CAAC;AAsBF;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAwFvF;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

package/dist/core/capability-tools.js

@@ -0,0 +1,202 @@
+"use strict";
+/**
+ * Capability Tools for AI-Powered Cluster Intelligence
+ *
+ * Shared tool definitions and executor for capability vector DB operations.
+ * Used by query, recommend, and other cluster intelligence workflows.
+ *
+ * PRD #291: Cluster Query Tool - Natural Language Cluster Intelligence
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CAPABILITY_TOOLS = exports.QUERY_CAPABILITIES_TOOL = exports.SEARCH_CAPABILITIES_TOOL = void 0;
+exports.executeCapabilityTools = executeCapabilityTools;
+exports.resetCapabilityService = resetCapabilityService;
+const capability_vector_service_1 = require("./capability-vector-service");
+/**
+ * Tool: search_capabilities
+ * Semantic search for cluster capabilities by intent/concept
+ */
+exports.SEARCH_CAPABILITIES_TOOL = {
+    name: 'search_capabilities',
+    description: `Semantic search for cluster capabilities. Use this to find what KINDS of resources relate to a concept (e.g., "database" returns StatefulSet, CNPG Cluster, Crossplane RDS). Returns capability definitions with semantic meaning, not actual resource instances.
+
+This tool is essential for the "semantic bridge" pattern:
+1. User asks about a concept (e.g., "databases", "message queues", "web servers")
+2. This tool finds which resource KINDS relate to that concept
+3. Then use query_resources or kubectl_get to find actual instances of those kinds
+
+Example: "database" might return capabilities for StatefulSet, clusters.postgresql.cnpg.io, compositions.apiextensions.crossplane.io (RDS), etc.`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'Semantic search query (e.g., "database", "message queue", "web server", "monitoring", "ingress controller")'
+            },
+            limit: {
+                type: 'number',
+                description: 'Maximum results to return (default: 10)'
+            }
+        },
+        required: ['query']
+    }
+};
+/**
+ * Tool: query_capabilities
+ * Filter-based query for capabilities using Qdrant filter syntax
+ */
+exports.QUERY_CAPABILITIES_TOOL = {
+    name: 'query_capabilities',
+    description: `Query capabilities using Qdrant filter syntax. Use this when you need to filter by specific fields like provider, complexity, or group - NOT for semantic/conceptual searches.
+
+Available payload fields for filtering:
+- resourceName: string (e.g., "Deployment", "StatefulSet", "Cluster")
+- group: string (e.g., "apps", "postgresql.cnpg.io", "apiextensions.crossplane.io")
+- apiVersion: string (e.g., "apps/v1", "postgresql.cnpg.io/v1")
+- providers: string[] (e.g., ["kubernetes", "crossplane", "cnpg"])
+- complexity: string ("low", "medium", "high")
+- capabilities: string[] (e.g., ["stateless-workload", "database", "networking"])
+- abstractions: string[] (e.g., ["container", "pod", "service"])
+- description: string (human-readable description)
+- useCase: string (recommended use cases)
+
+Qdrant filter syntax examples:
+- Filter by complexity: { "must": [{ "key": "complexity", "match": { "value": "low" } }] }
+- Filter by provider: { "must": [{ "key": "providers", "match": { "any": ["crossplane"] } }] }
+- Filter by group: { "must": [{ "key": "group", "match": { "value": "postgresql.cnpg.io" } }] }
+- Combined filter: { "must": [{ "key": "complexity", "match": { "value": "low" } }, { "key": "providers", "match": { "any": ["kubernetes"] } }] }`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            filter: {
+                type: 'object',
+                description: 'Qdrant filter object with must/should/must_not conditions'
+            },
+            limit: {
+                type: 'number',
+                description: 'Maximum results to return (default: 100)'
+            }
+        },
+        required: ['filter']
+    }
+};
+/**
+ * All capability tools for cluster intelligence
+ * Convenient array for passing to toolLoop()
+ */
+exports.CAPABILITY_TOOLS = [
+    exports.SEARCH_CAPABILITIES_TOOL,
+    exports.QUERY_CAPABILITIES_TOOL
+];
+/**
+ * Shared CapabilityVectorService instance for tool execution
+ * Initialized lazily on first use
+ */
+let capabilityService = null;
+/**
+ * Get or create the capability vector service
+ * Uses lazy initialization to avoid startup errors when Qdrant isn't ready
+ * Respects QDRANT_CAPABILITIES_COLLECTION env var for collection name
+ */
+async function getCapabilityService() {
+    if (!capabilityService) {
+        const collectionName = process.env.QDRANT_CAPABILITIES_COLLECTION || 'capabilities';
+        capabilityService = new capability_vector_service_1.CapabilityVectorService(collectionName);
+        await capabilityService.initialize();
+    }
+    return capabilityService;
+}
+/**
+ * Tool executor for capability-based tools
+ * Handles execution and error handling for all capability tool calls
+ *
+ * @param toolName - Name of the tool to execute
+ * @param input - Tool input parameters
+ * @returns Tool execution result
+ */
+async function executeCapabilityTools(toolName, input) {
+    try {
+        switch (toolName) {
+            case 'search_capabilities': {
+                const { query, limit = 10 } = input;
+                if (!query) {
+                    return {
+                        success: false,
+                        error: 'Missing required parameter: query',
+                        message: 'search_capabilities requires a query parameter'
+                    };
+                }
+                const service = await getCapabilityService();
+                const results = await service.searchCapabilities(query, { limit });
+                // Transform results to a clean format for AI consumption
+                const capabilities = results.map(r => ({
+                    resourceName: r.data.resourceName,
+                    group: r.data.group,
+                    apiVersion: r.data.apiVersion,
+                    complexity: r.data.complexity,
+                    providers: r.data.providers,
+                    capabilities: r.data.capabilities,
+                    description: r.data.description,
+                    useCase: r.data.useCase,
+                    score: r.score,
+                    matchType: r.matchType
+                }));
+                return {
+                    success: true,
+                    data: capabilities,
+                    count: capabilities.length,
+                    message: `Found ${capabilities.length} capabilities matching "${query}"`
+                };
+            }
+            case 'query_capabilities': {
+                const { filter, limit = 100 } = input;
+                if (!filter) {
+                    return {
+                        success: false,
+                        error: 'Missing required parameter: filter',
+                        message: 'query_capabilities requires a filter parameter with Qdrant filter syntax'
+                    };
+                }
+                const service = await getCapabilityService();
+                const results = await service.queryWithFilter(filter, limit);
+                // Transform results to a clean format for AI consumption
+                const capabilities = results.map(r => ({
+                    resourceName: r.resourceName,
+                    group: r.group,
+                    apiVersion: r.apiVersion,
+                    complexity: r.complexity,
+                    providers: r.providers,
+                    capabilities: r.capabilities,
+                    description: r.description,
+                    useCase: r.useCase
+                }));
+                return {
+                    success: true,
+                    data: capabilities,
+                    count: capabilities.length,
+                    message: `Found ${capabilities.length} capabilities matching filter`
+                };
+            }
+            default:
+                return {
+                    success: false,
+                    error: `Unknown capability tool: ${toolName}`,
+                    message: `Tool '${toolName}' is not implemented`
+                };
+        }
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            success: false,
+            error: errorMessage,
+            message: `Failed to execute ${toolName}: ${errorMessage}`
+        };
+    }
+}
+/**
+ * Reset the capability service (useful for testing)
+ */
+function resetCapabilityService() {
+    capabilityService = null;
+}

package/dist/core/resource-tools.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Resource Tools for AI-Powered Cluster Intelligence
+ *
+ * Shared tool definitions and executor for resource vector DB operations.
+ * Used by query and other cluster intelligence workflows.
+ *
+ * PRD #291: Cluster Query Tool - Natural Language Cluster Intelligence
+ */
+import { AITool } from './ai-provider.interface';
+/**
+ * Tool: search_resources
+ * Semantic search for cluster resources by name, kind, and labels
+ */
+export declare const SEARCH_RESOURCES_TOOL: AITool;
+/**
+ * Tool: query_resources
+ * Filter-based query for resources using Qdrant filter syntax
+ */
+export declare const QUERY_RESOURCES_TOOL: AITool;
+/**
+ * All resource tools for cluster intelligence
+ * Convenient array for passing to toolLoop()
+ */
+export declare const RESOURCE_TOOLS: AITool[];
+/**
+ * Tool executor for resource-based tools
+ * Handles execution and error handling for all resource tool calls
+ *
+ * @param toolName - Name of the tool to execute
+ * @param input - Tool input parameters
+ * @returns Tool execution result
+ */
+export declare function executeResourceTools(toolName: string, input: any): Promise<any>;
+/**
+ * Reset the resource service (useful for testing)
+ */
+export declare function resetResourceService(): void;
+//# sourceMappingURL=resource-tools.d.ts.map

package/dist/core/resource-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-tools.d.ts","sourceRoot":"","sources":["../../src/core/resource-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAGjD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,MA8BnC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAwClC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,EAGlC,CAAC;AAsBF;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CA0FrF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C"}

package/dist/core/resource-tools.js

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * Resource Tools for AI-Powered Cluster Intelligence
+ *
+ * Shared tool definitions and executor for resource vector DB operations.
+ * Used by query and other cluster intelligence workflows.
+ *
+ * PRD #291: Cluster Query Tool - Natural Language Cluster Intelligence
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESOURCE_TOOLS = exports.QUERY_RESOURCES_TOOL = exports.SEARCH_RESOURCES_TOOL = void 0;
+exports.executeResourceTools = executeResourceTools;
+exports.resetResourceService = resetResourceService;
+const resource_vector_service_1 = require("./resource-vector-service");
+/**
+ * Tool: search_resources
+ * Semantic search for cluster resources by name, kind, and labels
+ */
+exports.SEARCH_RESOURCES_TOOL = {
+    name: 'search_resources',
+    description: `Search for Kubernetes resources in the cluster inventory by name, kind, or labels. This searches the resource metadata stored in Vector DB.
+
+This tool is useful for:
+- Finding resources by partial name match (e.g., "nginx" finds nginx-deployment, nginx-service)
+- Finding resources by kind (e.g., "deployments" finds all Deployment resources)
+- Finding resources by label values (e.g., "frontend" finds resources with tier=frontend label)
+
+Note: This does NOT provide rich semantic understanding like search_capabilities. It matches against resource names, kinds, and label values - not conceptual descriptions. For example, searching "database" will NOT find a StatefulSet unless it has "database" in its name or labels.
+
+For conceptual queries like "what databases are running", use the semantic bridge pattern:
+1. Use search_capabilities to find what KINDS relate to "database"
+2. Then use query_resources to find instances of those kinds
+
+For live cluster status, use kubectl tools after finding resources.`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'Search query matching resource names, kinds, or label values (e.g., "nginx", "Deployment", "frontend")'
+            },
+            limit: {
+                type: 'number',
+                description: 'Maximum results to return (default: 10)'
+            }
+        },
+        required: ['query']
+    }
+};
+/**
+ * Tool: query_resources
+ * Filter-based query for resources using Qdrant filter syntax
+ */
+exports.QUERY_RESOURCES_TOOL = {
+    name: 'query_resources',
+    description: `Query cluster resources using Qdrant filter syntax. Use this when you need to filter by specific fields like kind, namespace, or labels.
+
+This is the primary tool for finding resource instances after using search_capabilities to identify relevant kinds.
+
+Available payload fields for filtering:
+- id: string (format: namespace:apiVersion:kind:name)
+- namespace: string (e.g., "default", "kube-system", "_cluster" for cluster-scoped)
+- name: string (resource name)
+- kind: string (e.g., "Deployment", "Service", "Pod", "StatefulSet")
+- apiVersion: string (e.g., "apps/v1", "v1")
+- apiGroup: string (e.g., "apps", "", "postgresql.cnpg.io")
+- labels: object (e.g., { "app": "nginx", "env": "prod" })
+- annotations: object (resource annotations)
+- createdAt: string (ISO timestamp)
+- updatedAt: string (ISO timestamp)
+
+Qdrant filter syntax examples:
+- Filter by kind: { "must": [{ "key": "kind", "match": { "value": "Deployment" } }] }
+- Filter by namespace: { "must": [{ "key": "namespace", "match": { "value": "default" } }] }
+- Filter by multiple kinds: { "must": [{ "key": "kind", "match": { "any": ["Deployment", "StatefulSet"] } }] }
+- Filter by label: { "must": [{ "key": "labels.app", "match": { "value": "nginx" } }] }
+- Combined filter: { "must": [{ "key": "kind", "match": { "value": "Deployment" } }, { "key": "namespace", "match": { "value": "production" } }] }
+
+Note: This queries the resource inventory in Vector DB, not live cluster state.`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            filter: {
+                type: 'object',
+                description: 'Qdrant filter object with must/should/must_not conditions'
+            },
+            limit: {
+                type: 'number',
+                description: 'Maximum results to return (default: 100)'
+            }
+        },
+        required: ['filter']
+    }
+};
+/**
+ * All resource tools for cluster intelligence
+ * Convenient array for passing to toolLoop()
+ */
+exports.RESOURCE_TOOLS = [
+    exports.SEARCH_RESOURCES_TOOL,
+    exports.QUERY_RESOURCES_TOOL
+];
+/**
+ * Shared ResourceVectorService instance for tool execution
+ * Initialized lazily on first use
+ */
+let resourceService = null;
+/**
+ * Get or create the resource vector service
+ * Uses lazy initialization to avoid startup errors when Qdrant isn't ready
+ * Respects QDRANT_RESOURCES_COLLECTION env var for collection name
+ */
+async function getResourceService() {
+    if (!resourceService) {
+        const collectionName = process.env.QDRANT_RESOURCES_COLLECTION || 'resources';
+        resourceService = new resource_vector_service_1.ResourceVectorService(collectionName);
+        await resourceService.initialize();
+    }
+    return resourceService;
+}
+/**
+ * Tool executor for resource-based tools
+ * Handles execution and error handling for all resource tool calls
+ *
+ * @param toolName - Name of the tool to execute
+ * @param input - Tool input parameters
+ * @returns Tool execution result
+ */
+async function executeResourceTools(toolName, input) {
+    try {
+        switch (toolName) {
+            case 'search_resources': {
+                const { query, limit = 10 } = input;
+                if (!query) {
+                    return {
+                        success: false,
+                        error: 'Missing required parameter: query',
+                        message: 'search_resources requires a query parameter'
+                    };
+                }
+                const service = await getResourceService();
+                const results = await service.searchData(query, { limit });
+                // Transform results to a clean format for AI consumption
+                const resources = results.map(r => ({
+                    id: r.data.id,
+                    namespace: r.data.namespace,
+                    name: r.data.name,
+                    kind: r.data.kind,
+                    apiVersion: r.data.apiVersion,
+                    apiGroup: r.data.apiGroup,
+                    labels: r.data.labels,
+                    createdAt: r.data.createdAt,
+                    updatedAt: r.data.updatedAt,
+                    score: r.score,
+                    matchType: r.matchType
+                }));
+                return {
+                    success: true,
+                    data: resources,
+                    count: resources.length,
+                    message: `Found ${resources.length} resources matching "${query}"`
+                };
+            }
+            case 'query_resources': {
+                const { filter, limit = 100 } = input;
+                if (!filter) {
+                    return {
+                        success: false,
+                        error: 'Missing required parameter: filter',
+                        message: 'query_resources requires a filter parameter with Qdrant filter syntax'
+                    };
+                }
+                const service = await getResourceService();
+                const results = await service.queryWithFilter(filter, limit);
+                // Transform results to a clean format for AI consumption
+                const resources = results.map(r => ({
+                    id: r.id,
+                    namespace: r.namespace,
+                    name: r.name,
+                    kind: r.kind,
+                    apiVersion: r.apiVersion,
+                    apiGroup: r.apiGroup,
+                    labels: r.labels,
+                    createdAt: r.createdAt,
+                    updatedAt: r.updatedAt
+                }));
+                return {
+                    success: true,
+                    data: resources,
+                    count: resources.length,
+                    message: `Found ${resources.length} resources matching filter`
+                };
+            }
+            default:
+                return {
+                    success: false,
+                    error: `Unknown resource tool: ${toolName}`,
+                    message: `Tool '${toolName}' is not implemented`
+                };
+        }
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            success: false,
+            error: errorMessage,
+            message: `Failed to execute ${toolName}: ${errorMessage}`
+        };
+    }
+}
+/**
+ * Reset the resource service (useful for testing)
+ */
+function resetResourceService() {
+    resourceService = null;
+}

package/dist/core/resource-vector-service.d.ts

@@ -45,6 +45,15 @@ export interface SyncResult {
         error: string;
     }>;
 }
+/**
+ * Simplified resource identifier for tracking changes
+ */
+export interface ResourceIdentifier {
+    namespace: string;
+    kind: string;
+    name: string;
+    apiVersion: string;
+}
 /**
  * Result of a diff and sync operation
  */
@@ -52,6 +61,9 @@ export interface DiffSyncResult {
     inserted: number;
     updated: number;
     deleted: number;
+    insertedResources: ResourceIdentifier[];
+    updatedResources: ResourceIdentifier[];
+    deletedResources: ResourceIdentifier[];
 }
 /**
  * Extract API group from apiVersion

package/dist/core/resource-vector-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource-vector-service.d.ts","sourceRoot":"","sources":["../../src/core/resource-vector-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resource-vector-service.d.ts","sourceRoot":"","sources":["../../src/core/resource-vector-service.ts"],"names":[],"mappings":"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"}

package/dist/core/resource-vector-service.js

@@ -233,13 +233,20 @@ class ResourceVectorService extends base_vector_service_1.BaseVectorService {
     async diffAndSync(incoming) {
         // Helper to get human-readable ID from resource
         const getResourceKey = (r) => generateResourceId(r.namespace, r.apiVersion, r.kind, r.name);
+        // Helper to extract resource identifier
+        const toResourceIdentifier = (r) => ({
+            namespace: r.namespace,
+            kind: r.kind,
+            name: r.name,
+            apiVersion: r.apiVersion
+        });
         // Get all existing resources from Qdrant
         const existing = await this.listResources();
         const existingMap = new Map(existing.map(r => [getResourceKey(r), r]));
         const incomingMap = new Map(incoming.map(r => [getResourceKey(r), r]));
         const toInsert = [];
         const toUpdate = [];
-        const toDelete = [];
+        const toDeleteResources = [];
         // Find new and changed resources
         for (const resource of incoming) {
             const resourceId = getResourceKey(resource);
@@ -252,22 +259,26 @@ class ResourceVectorService extends base_vector_service_1.BaseVectorService {
             }
         }
         // Find deleted resources (in Qdrant but not in incoming)
-        for (const id of existingMap.keys()) {
+        for (const [id, resource] of existingMap.entries()) {
             if (!incomingMap.has(id)) {
-                toDelete.push(id);
+                toDeleteResources.push(resource);
             }
         }
         // Apply changes
         for (const resource of [...toInsert, ...toUpdate]) {
             await this.storeResource(resource);
         }
-        for (const id of toDelete) {
+        for (const resource of toDeleteResources) {
+            const id = getResourceKey(resource);
             await this.deleteResource(id);
         }
         return {
             inserted: toInsert.length,
             updated: toUpdate.length,
-            deleted: toDelete.length
+            deleted: toDeleteResources.length,
+            insertedResources: toInsert.map(toResourceIdentifier),
+            updatedResources: toUpdate.map(toResourceIdentifier),
+            deletedResources: toDeleteResources.map(toResourceIdentifier)
         };
     }
 }

package/dist/core/tracing/qdrant-tracing.d.ts

@@ -7,7 +7,7 @@
 /**
  * Vector database operation types
  */
-export type VectorDBOperation = 'collection.create' | 'collection.get' | 'collection.list' | 'collection.delete' | 'collection.initialize' | 'vector.upsert' | 'vector.search' | 'vector.search_keywords' | 'vector.retrieve' | 'vector.delete' | 'vector.delete_all' | 'vector.list' | 'health_check';
+export type VectorDBOperation = 'collection.create' | 'collection.get' | 'collection.list' | 'collection.delete' | 'collection.initialize' | 'vector.upsert' | 'vector.search' | 'vector.search_keywords' | 'vector.scroll_filtered' | 'vector.retrieve' | 'vector.delete' | 'vector.delete_all' | 'vector.list' | 'health_check';
 /**
  * Qdrant operation metadata for tracing
  */