@equationalapplications/core-llm-tools 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Equational Applications LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# @equationalapplications/core-llm-tools
+
+Platform-agnostic Gemini tool schemas and a capability-based scope injector.
+
+[![npm version](https://img.shields.io/npm/v/%40equationalapplications%2Fcore-llm-tools?label=core-llm-tools)](https://www.npmjs.com/package/@equationalapplications/core-llm-tools)
+[![npm downloads](https://img.shields.io/npm/dm/%40equationalapplications%2Fcore-llm-tools?label=downloads)](https://www.npmjs.com/package/@equationalapplications/core-llm-tools)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+> A universal registry bridging the gap between Edge AI (Expo/React Native) and Cloud Agents (Cloud Run).
+
+## Overview
+
+`core-llm-tools` provides a shared, strictly-typed repository of JSON Function Declarations (Tools) for Gemini models. By decoupling the **Tool Interface** (the schema) from the **Tool Implementation** (the executing code), this package allows client-side triage agents and heavy backend cloud agents to share the exact same capabilities without importing Node.js server dependencies into the browser or mobile environments.
+
+It also introduces a robust **Capability-Based Scope Model** (similar to OAuth 2.0), ensuring that Large Language Models are only injected with tools the user has explicitly authorized.
+
+## Features
+
+- **Platform-Agnostic** — Zero runtime dependencies. Pure TypeScript. Compiles safely for Node.js, the browser, and the React Native Hermes engine.
+- **Capability-Based Security** — Tools are locked behind specific scopes (e.g., `calendar:read`, `messages:send`). The injector ensures models cannot hallucinate calls to unauthorized tools.
+- **Strict Typings** — Provides rigid interfaces (`AgentToolSchema`, `AgentToolManifest`) to prevent malformed Gemini API requests.
+- **Harmonized Edge/Cloud Routing** — Enables lightweight edge models (like Gemini Nano) to triage intents using the exact same schemas the heavy Cloud Run backend uses to execute them.
+
+## Installation
+
+```bash
+npm install @equationalapplications/core-llm-tools
+# or
+pnpm add @equationalapplications/core-llm-tools
+```
+
+## Quick Start
+
+### 1. Defining a Tool Manifest
+
+Tools are defined by wrapping a standard Gemini JSON schema with a required security scope.
+
+```typescript
+import type { AgentToolManifest } from '@equationalapplications/core-llm-tools';
+
+export const getCalendarEventsManifest: AgentToolManifest = {
+  name: 'get_calendar_events',
+  scope: 'calendar:read', // Security scope required to use this tool
+  schema: {
+    name: 'get_calendar_events',
+    description: 'Fetch the user\'s schedule for a given date.',
+    parameters: {
+      type: 'object',
+      properties: {
+        date: { type: 'string' }
+      }
+    }
+  }
+};
+```
+
+### 2. Injecting Authorized Tools
+
+At runtime, use `buildAuthorizedSchemaArray` to filter your tool library against the user's granted permissions before passing them to the LLM.
+
+```typescript
+import { buildAuthorizedSchemaArray, escalateToCloudManifest } from '@equationalapplications/core-llm-tools';
+
+// 1. Gather all manifests known to your app
+const allAppTools = [escalateToCloudManifest, getCalendarEventsManifest];
+
+// 2. Fetch the user's authorized scopes from your DB (e.g., SQLite/Postgres)
+const userGrantedScopes = ['calendar:read'];
+
+// 3. The injector automatically includes 'core' tools and authorized scoped tools
+const schemasForLlm = buildAuthorizedSchemaArray(allAppTools, userGrantedScopes);
+
+// 4. Pass safely to Gemini
+const response = await ai.models.generateContent({
+  model: 'gemini-2.5-flash',
+  contents: userInput,
+  tools: [{ functionDeclarations: schemasForLlm }],
+});
+```
+
+## Helpful Resources & Links
+
+- [Google Gen AI: Function Calling Tutorial](https://ai.google.dev/gemini-api/docs/function-calling) — Official docs on how the JSON schemas in this package interact with Gemini models.
+- [JSON Schema Specification](https://json-schema.org/understanding-json-schema/) — Structural foundation for `AgentToolSchema.parameters`.
+- [OAuth 2.0 Scope Concepts](https://oauth.net/2/scope/) — Inspiration behind the capability-based `AgentScope` permission hierarchy.
+- [@google/adk (Agent Development Kit)](https://github.com/google/adk-python) — Server-side framework used by Cloud Run backends to wrap and execute the schemas defined in this package.

package/dist/index.d.mts

@@ -0,0 +1,22 @@
+type AgentScope = 'core' | 'location:read' | 'calendar:read' | 'calendar:write' | 'messages:send' | 'memory:read' | 'memory:write';
+interface AgentToolSchema {
+    name: string;
+    description: string;
+    parameters?: {
+        type: 'object' | 'string' | 'number' | 'boolean' | 'array';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+interface AgentToolManifest {
+    name: string;
+    scope: AgentScope;
+    schema: AgentToolSchema;
+}
+
+declare function buildAuthorizedSchemaArray(availableManifests: AgentToolManifest[], userGrantedScopes: string[]): AgentToolSchema[];
+
+declare const getCurrentTimeManifest: AgentToolManifest;
+declare const escalateToCloudManifest: AgentToolManifest;
+
+export { type AgentScope, type AgentToolManifest, type AgentToolSchema, buildAuthorizedSchemaArray, escalateToCloudManifest, getCurrentTimeManifest };

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+type AgentScope = 'core' | 'location:read' | 'calendar:read' | 'calendar:write' | 'messages:send' | 'memory:read' | 'memory:write';
+interface AgentToolSchema {
+    name: string;
+    description: string;
+    parameters?: {
+        type: 'object' | 'string' | 'number' | 'boolean' | 'array';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+interface AgentToolManifest {
+    name: string;
+    scope: AgentScope;
+    schema: AgentToolSchema;
+}
+
+declare function buildAuthorizedSchemaArray(availableManifests: AgentToolManifest[], userGrantedScopes: string[]): AgentToolSchema[];
+
+declare const getCurrentTimeManifest: AgentToolManifest;
+declare const escalateToCloudManifest: AgentToolManifest;
+
+export { type AgentScope, type AgentToolManifest, type AgentToolSchema, buildAuthorizedSchemaArray, escalateToCloudManifest, getCurrentTimeManifest };

package/dist/index.js

@@ -0,0 +1,34 @@
+'use strict';
+
+// src/injector.ts
+function buildAuthorizedSchemaArray(availableManifests, userGrantedScopes) {
+  return availableManifests.filter(
+    (manifest) => manifest.scope === "core" || userGrantedScopes.includes(manifest.scope)
+  ).map((manifest) => manifest.schema);
+}
+
+// src/manifests/core.ts
+var getCurrentTimeManifest = {
+  name: "get_current_time",
+  scope: "core",
+  schema: {
+    name: "get_current_time",
+    description: 'Get the exact current date and time. Always call this tool first if resolving relative temporal words like "today" or "tomorrow".',
+    parameters: { type: "object", properties: {} }
+  }
+};
+var escalateToCloudManifest = {
+  name: "escalate_to_cloud_agent",
+  scope: "core",
+  schema: {
+    name: "escalate_to_cloud_agent",
+    description: "Use this tool when the user asks to schedule a reminder, perform deep memory searches, or execute a complex workflow that requires cloud resources.",
+    parameters: { type: "object", properties: {} }
+  }
+};
+
+exports.buildAuthorizedSchemaArray = buildAuthorizedSchemaArray;
+exports.escalateToCloudManifest = escalateToCloudManifest;
+exports.getCurrentTimeManifest = getCurrentTimeManifest;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/injector.ts","../src/manifests/core.ts"],"names":[],"mappings":";;;AAEO,SAAS,0BAAA,CACd,oBACA,iBAAA,EACmB;AACnB,EAAA,OAAO,kBAAA,CACJ,MAAA;AAAA,IACC,CAAC,aACC,QAAA,CAAS,KAAA,KAAU,UAAU,iBAAA,CAAkB,QAAA,CAAS,SAAS,KAAK;AAAA,GAC1E,CACC,GAAA,CAAI,CAAC,QAAA,KAAa,SAAS,MAAM,CAAA;AACtC;;;ACVO,IAAM,sBAAA,GAA4C;AAAA,EACvD,IAAA,EAAM,kBAAA;AAAA,EACN,KAAA,EAAO,MAAA;AAAA,EACP,MAAA,EAAQ;AAAA,IACN,IAAA,EAAM,kBAAA;AAAA,IACN,WAAA,EACE,mIAAA;AAAA,IACF,YAAY,EAAE,IAAA,EAAM,QAAA,EAAU,UAAA,EAAY,EAAC;AAAE;AAEjD;AAEO,IAAM,uBAAA,GAA6C;AAAA,EACxD,IAAA,EAAM,yBAAA;AAAA,EACN,KAAA,EAAO,MAAA;AAAA,EACP,MAAA,EAAQ;AAAA,IACN,IAAA,EAAM,yBAAA;AAAA,IACN,WAAA,EACE,qJAAA;AAAA,IACF,YAAY,EAAE,IAAA,EAAM,QAAA,EAAU,UAAA,EAAY,EAAC;AAAE;AAEjD","file":"index.js","sourcesContent":["import type { AgentToolManifest, AgentToolSchema } from './types';\n\nexport function buildAuthorizedSchemaArray(\n  availableManifests: AgentToolManifest[],\n  userGrantedScopes: string[]\n): AgentToolSchema[] {\n  return availableManifests\n    .filter(\n      (manifest) =>\n        manifest.scope === 'core' || userGrantedScopes.includes(manifest.scope)\n    )\n    .map((manifest) => manifest.schema);\n}\n","import type { AgentToolManifest } from '../types';\n\nexport const getCurrentTimeManifest: AgentToolManifest = {\n  name: 'get_current_time',\n  scope: 'core',\n  schema: {\n    name: 'get_current_time',\n    description:\n      'Get the exact current date and time. Always call this tool first if resolving relative temporal words like \"today\" or \"tomorrow\".',\n    parameters: { type: 'object', properties: {} },\n  },\n};\n\nexport const escalateToCloudManifest: AgentToolManifest = {\n  name: 'escalate_to_cloud_agent',\n  scope: 'core',\n  schema: {\n    name: 'escalate_to_cloud_agent',\n    description:\n      'Use this tool when the user asks to schedule a reminder, perform deep memory searches, or execute a complex workflow that requires cloud resources.',\n    parameters: { type: 'object', properties: {} },\n  },\n};\n"]}

package/dist/index.mjs

@@ -0,0 +1,30 @@
+// src/injector.ts
+function buildAuthorizedSchemaArray(availableManifests, userGrantedScopes) {
+  return availableManifests.filter(
+    (manifest) => manifest.scope === "core" || userGrantedScopes.includes(manifest.scope)
+  ).map((manifest) => manifest.schema);
+}
+
+// src/manifests/core.ts
+var getCurrentTimeManifest = {
+  name: "get_current_time",
+  scope: "core",
+  schema: {
+    name: "get_current_time",
+    description: 'Get the exact current date and time. Always call this tool first if resolving relative temporal words like "today" or "tomorrow".',
+    parameters: { type: "object", properties: {} }
+  }
+};
+var escalateToCloudManifest = {
+  name: "escalate_to_cloud_agent",
+  scope: "core",
+  schema: {
+    name: "escalate_to_cloud_agent",
+    description: "Use this tool when the user asks to schedule a reminder, perform deep memory searches, or execute a complex workflow that requires cloud resources.",
+    parameters: { type: "object", properties: {} }
+  }
+};
+
+export { buildAuthorizedSchemaArray, escalateToCloudManifest, getCurrentTimeManifest };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/injector.ts","../src/manifests/core.ts"],"names":[],"mappings":";AAEO,SAAS,0BAAA,CACd,oBACA,iBAAA,EACmB;AACnB,EAAA,OAAO,kBAAA,CACJ,MAAA;AAAA,IACC,CAAC,aACC,QAAA,CAAS,KAAA,KAAU,UAAU,iBAAA,CAAkB,QAAA,CAAS,SAAS,KAAK;AAAA,GAC1E,CACC,GAAA,CAAI,CAAC,QAAA,KAAa,SAAS,MAAM,CAAA;AACtC;;;ACVO,IAAM,sBAAA,GAA4C;AAAA,EACvD,IAAA,EAAM,kBAAA;AAAA,EACN,KAAA,EAAO,MAAA;AAAA,EACP,MAAA,EAAQ;AAAA,IACN,IAAA,EAAM,kBAAA;AAAA,IACN,WAAA,EACE,mIAAA;AAAA,IACF,YAAY,EAAE,IAAA,EAAM,QAAA,EAAU,UAAA,EAAY,EAAC;AAAE;AAEjD;AAEO,IAAM,uBAAA,GAA6C;AAAA,EACxD,IAAA,EAAM,yBAAA;AAAA,EACN,KAAA,EAAO,MAAA;AAAA,EACP,MAAA,EAAQ;AAAA,IACN,IAAA,EAAM,yBAAA;AAAA,IACN,WAAA,EACE,qJAAA;AAAA,IACF,YAAY,EAAE,IAAA,EAAM,QAAA,EAAU,UAAA,EAAY,EAAC;AAAE;AAEjD","file":"index.mjs","sourcesContent":["import type { AgentToolManifest, AgentToolSchema } from './types';\n\nexport function buildAuthorizedSchemaArray(\n  availableManifests: AgentToolManifest[],\n  userGrantedScopes: string[]\n): AgentToolSchema[] {\n  return availableManifests\n    .filter(\n      (manifest) =>\n        manifest.scope === 'core' || userGrantedScopes.includes(manifest.scope)\n    )\n    .map((manifest) => manifest.schema);\n}\n","import type { AgentToolManifest } from '../types';\n\nexport const getCurrentTimeManifest: AgentToolManifest = {\n  name: 'get_current_time',\n  scope: 'core',\n  schema: {\n    name: 'get_current_time',\n    description:\n      'Get the exact current date and time. Always call this tool first if resolving relative temporal words like \"today\" or \"tomorrow\".',\n    parameters: { type: 'object', properties: {} },\n  },\n};\n\nexport const escalateToCloudManifest: AgentToolManifest = {\n  name: 'escalate_to_cloud_agent',\n  scope: 'core',\n  schema: {\n    name: 'escalate_to_cloud_agent',\n    description:\n      'Use this tool when the user asks to schedule a reminder, perform deep memory searches, or execute a complex workflow that requires cloud resources.',\n    parameters: { type: 'object', properties: {} },\n  },\n};\n"]}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@equationalapplications/core-llm-tools",
+  "version": "0.1.0",
+  "description": "Platform-agnostic Gemini tool schemas and capability-based scope injector.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "4.1.5"
+  }
+}