@zenera/rag 1.1.39 → 1.1.41

package/dist/schema/tools.d.ts

@@ -1,5 +1,7 @@
 import { type AnyTool } from '@zenera/neo';
+import type { ApiGraph } from './graph.ts';
 import { type Format } from './present.ts';
+import type { Schema } from './schema.ts';
 import type { SchemaIndex } from './search.ts';
 export interface SchemaToolOptions {
     /** what `format` defaults to when the model does not say */
@@ -8,5 +10,23 @@ export interface SchemaToolOptions {
     /** name the document each answer came from; on by default past one document */
     source?: boolean;
 }
+/**
+ * An API graph without an index around it: what every tool but `search_api`
+ * needs. A caller that built the graph itself — from the documents, in memory —
+ * gets the exact tools without paying for vectors it would never search.
+ */
+export interface GraphSource {
+    graph: ApiGraph;
+    /** the documents' names, as each node's `source` says them */
+    sources: readonly string[];
+    /** the raw schemas by type id, for TypeScript declarations */
+    schemas(): Promise<Readonly<Record<string, Schema>>>;
+}
 export declare function schemaTools<TCtx = unknown>(index: SchemaIndex, options?: SchemaToolOptions): AnyTool<TCtx>[];
+/**
+ * The five exact tools — no ranking, no embedder — over a graph alone:
+ * `describe_types`, `find_types_with_property`, `list_api`, `grep_api` and
+ * `trace_api`. `schemaTools` is these plus `search_api`.
+ */
+export declare function graphTools<TCtx = unknown>(api: GraphSource, options?: SchemaToolOptions): AnyTool<TCtx>[];
 //# sourceMappingURL=tools.d.ts.map

package/dist/schema/tools.js

@@ -148,6 +148,19 @@ export function schemaTools(index, options = {}) {
             };
         },
     });
+    return [
+        searchApi,
+        ...graphTools({ graph: index.graph, sources: names, schemas: () => index.schemas() }, options),
+    ];
+}
+/**
+ * The five exact tools — no ranking, no embedder — over a graph alone:
+ * `describe_types`, `find_types_with_property`, `list_api`, `grep_api` and
+ * `trace_api`. `schemaTools` is these plus `search_api`.
+ */
+export function graphTools(api, options = {}) {
+    const docs = options.docs ?? true;
+    const source = options.source ?? api.sources.length > 1;
     const describeTypes = tool({
         name: 'describe_types',
         group: GROUP,
@@ -164,7 +177,7 @@ export function schemaTools(index, options = {}) {
             additionalProperties: false,
         },
         execute: async ({ names, only }) => {
-            const known = names.filter((name) => index.graph.hasNode(`Type:${name}`));
+            const known = names.filter((name) => api.graph.hasNode(`Type:${name}`));
             const missing = names.filter((name) => !known.includes(name));
             if (known.length === 0) {
                 return {
@@ -172,8 +185,8 @@ export function schemaTools(index, options = {}) {
                     hint: 'search for it first',
                 };
             }
-            const schemas = await index.schemas();
-            const sub = subgraphOf(index, known.map((name) => `Type:${name}`));
+            const schemas = await api.schemas();
+            const sub = subgraphOf(api.graph, known.map((name) => `Type:${name}`));
             const code = toTypeScript(sub, schemas, { docs, onlyHits: false });
             return {
                 typescript: only?.length ? narrow(code, only) : code,
@@ -203,11 +216,11 @@ export function schemaTools(index, options = {}) {
         execute: async ({ property, direction }) => {
             const wanted = property.toLowerCase();
             const candidates = [];
-            index.graph.forEachNode((id, a) => {
+            api.graph.forEachNode((id, a) => {
                 if (a.kind !== 'property' || a.name.toLowerCase() !== wanted || !a.parent) {
                     return;
                 }
-                const owner = index.graph.getNodeAttributes(`Type:${a.parent}`) ?? a;
+                const owner = api.graph.getNodeAttributes(`Type:${a.parent}`) ?? a;
                 if (direction && direction !== 'any' && !onSide(owner.direction, direction)) {
                     return;
                 }
@@ -278,7 +291,7 @@ export function schemaTools(index, options = {}) {
             }
             let result;
             try {
-                result = listNodes(index.graph, {
+                result = listNodes(api.graph, {
                     kind: subject,
                     name: name ? [loose(name, { regex })] : undefined,
                     path: path ? [loose(path, { regex })] : undefined,
@@ -294,7 +307,7 @@ export function schemaTools(index, options = {}) {
             return {
                 found: result.found,
                 truncated: result.truncated,
-                [PLURALS[subject]]: result.rows.map((r) => line(index.graph, subject, r, source)),
+                [PLURALS[subject]]: result.rows.map((r) => line(api.graph, subject, r, source)),
             };
         },
     });
@@ -342,7 +355,7 @@ export function schemaTools(index, options = {}) {
         execute: async ({ pattern, regex, kind, name, path, source: only, limit }) => {
             let result;
             try {
-                result = grepNodes(index.graph, matcher(pattern, { regex }), {
+                result = grepNodes(api.graph, matcher(pattern, { regex }), {
                     kinds: kind ? [kind] : undefined,
                     name: name ? [loose(name)] : undefined,
                     path: path ? [loose(path)] : undefined,
@@ -417,10 +430,10 @@ export function schemaTools(index, options = {}) {
         execute: async ({ of: wanted, kind, direction, source: only, limit, routes }) => {
             let result;
             try {
-                result = traceNodes(index.graph, {
-                    ids: index.graph.hasNode(wanted) ? [wanted] : undefined,
+                result = traceNodes(api.graph, {
+                    ids: api.graph.hasNode(wanted) ? [wanted] : undefined,
                     kinds: kind ? [kind] : undefined,
-                    name: index.graph.hasNode(wanted) ? undefined : [loose(wanted)],
+                    name: api.graph.hasNode(wanted) ? undefined : [loose(wanted)],
                     source: only,
                     limit: Math.min(limit ?? DEFAULT_TRACES, MAX_TRACES),
                     maxRoutes: Math.min(routes ?? DEFAULT_ROUTES, MAX_ROWS),
@@ -445,12 +458,12 @@ export function schemaTools(index, options = {}) {
                     operations: t.routes
                         .filter((r) => !side || r.direction === side || r.direction === 'both')
                         .map((r) => `${r.attributes.httpMethod} ${r.attributes.path}  ` +
-                        `${r.attributes.name}  (${r.direction})${source ? `  ${sourceTag(r.attributes.source)}` : ''}  ${chainOf(index.graph, t.id, r)}`),
+                        `${r.attributes.name}  (${r.direction})${source ? `  ${sourceTag(r.attributes.source)}` : ''}  ${chainOf(api.graph, t.id, r)}`),
                 })),
             };
         },
     });
-    return [searchApi, describeTypes, findTypesWithProperty, listApi, grepApi, traceApi];
+    return [describeTypes, findTypesWithProperty, listApi, grepApi, traceApi];
 }
 // ---------------------------------------------------------------------------
 const SUBJECTS = {
@@ -487,8 +500,8 @@ function chosen(format, fallback) {
 function onSide(direction, wanted) {
     return direction === wanted || direction === 'both';
 }
-function subgraphOf(index, ids) {
-    const [first] = stitch(index.graph, ids.map((id) => ({ id, term: id, field: 'describe', score: 1 })), { maxNodes: DEFAULT_MAX_NODES * ids.length });
+function subgraphOf(graph, ids) {
+    const [first] = stitch(graph, ids.map((id) => ({ id, term: id, field: 'describe', score: 1 })), { maxNodes: DEFAULT_MAX_NODES * ids.length });
     return first ?? { nodes: [], edges: [], hits: [], score: 0, truncated: false };
 }
 /** Keeps the declarations, drops the field lines nobody asked about. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/rag",
-    "version": "1.1.39",
+    "version": "1.1.41",
     "description": "Retrieval over a corpus: openapi/swagger documents as a searchable graph, markdown and text as searchable passages.",
     "keywords": [
         "agents",
@@ -61,8 +61,8 @@
     "dependencies": {
         "@apidevtools/swagger-parser": "^12.0.0",
         "@lancedb/lancedb": "^0.38.0",
-        "@zenera/cli": "^1.1.39",
-        "@zenera/neo": "^1.1.39",
+        "@zenera/cli": "^1.1.41",
+        "@zenera/neo": "^1.1.41",
         "graphology": "^0.26.0",
         "remark-frontmatter": "^5.0.0",
         "remark-gfm": "^4.0.1",