@kirha/planner 0.1.0

package/dist/parser/index.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+import { type ParamsValue, type PlanStep } from "../types";
+export declare const ParamSchema: z.ZodType<ParamsValue>;
+export declare function parseModelOutput(raw: string): {
+    think: string | undefined;
+    plan: PlanStep[] | undefined;
+};
+export declare function parsePlanSteps(rawSteps: string): PlanStep[];

package/dist/parser/template-string-parser.d.ts

@@ -0,0 +1,2 @@
+import type { StringTemplateReference } from "../types";
+export declare function parseTemplateString(tpl: string, stepIdByIndex: Map<number, string>): StringTemplateReference | string;

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+export type ToolHandler<TInput = unknown, TOutput = unknown> = (args: TInput) => Promise<TOutput>;
+export interface Tool<TInput = unknown, TOutput = unknown> {
+    name: string;
+    description: string;
+    inputSchema: string;
+    outputSchema: string;
+    handler: ToolHandler<TInput, TOutput>;
+}
+export interface StepResult {
+    stepId: string;
+    toolName: string;
+    arguments: Record<string, unknown>;
+    output: unknown;
+    error?: string;
+}
+export type PlanValidationErrorCode = "tool_not_found" | "schema_parse_error" | "dependency_step_missing" | "input_key_missing" | "output_key_missing" | "type_mismatch";
+export interface PlanValidationError {
+    code: PlanValidationErrorCode;
+    message: string;
+    stepId?: string;
+    toolName?: string;
+    argumentPath?: string;
+    fromStepId?: string;
+    outputPath?: string;
+    expectedType?: string;
+    actualType?: string;
+}
+export interface PlanValidationResult {
+    valid: boolean;
+    errors: PlanValidationError[];
+}
+export interface DependencyReference {
+    $fromStep: string;
+    $outputKey: string;
+}
+export interface StringTemplateReference {
+    $fromTemplateString: string;
+    $values: DependencyReference[];
+}
+export interface RawDependencyReference {
+    fromStep: number;
+    outputKey: string;
+}
+export type ParamsValue = string | number | boolean | null | ParamObject | DependencyReference | StringTemplateReference | Array<ParamsValue | DependencyReference>;
+interface ParamObject {
+    [key: string]: ParamsValue;
+}
+export type PlanStepParams = Record<string, ParamsValue>;
+export declare enum PlanStepStatus {
+    Pending = "pending",
+    Executing = "executing",
+    Done = "done",
+    Failed = "failed",
+    Skipped = "skipped",
+    Timeout = "timeout"
+}
+export interface PlanStep {
+    stepId: string;
+    status: PlanStepStatus;
+    toolName: string;
+    arguments: PlanStepParams;
+    thought?: string;
+}
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,17 @@
+import type { DependencyReference, RawDependencyReference, StringTemplateReference } from "./types";
+export type PathSegment = string | number;
+export type Path = PathSegment[];
+export declare function parsePath(path: string): Path;
+export declare function normalizePath(path: string): string;
+export declare function formatPath(path: Path): string;
+export declare function isNumericString(value: string): boolean;
+export declare function getNestedValue(obj: unknown, path: Path): unknown;
+export type ReferenceCallbacks = {
+    onDependency?: (ref: DependencyReference, path: Path) => void;
+    onTemplate?: (ref: StringTemplateReference, path: Path) => void;
+};
+export declare function traverseReferences(value: unknown, callbacks: ReferenceCallbacks, currentPath?: Path): void;
+export declare function extractDependencyStepIds(args: Record<string, unknown>): string[];
+export declare function isDependencyReference(value: unknown): value is DependencyReference;
+export declare function isStringTemplateReference(value: unknown): value is StringTemplateReference;
+export declare function isRawDependencyReference(value: unknown): value is RawDependencyReference;

package/dist/validator/index.d.ts

@@ -0,0 +1,2 @@
+import type { PlanStep, PlanValidationResult, Tool } from "../types";
+export declare function isValidPlan(steps: PlanStep[], tools: Tool[]): PlanValidationResult;

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@kirha/planner",
+  "version": "0.1.0",
+  "description": "SDK for tool-planning agents - generate and execute DAG execution plans from natural language",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target node && bun run build:types",
+    "build:types": "tsc --project tsconfig.build.json",
+    "test": "bun test",
+    "lint": "biome check --write",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "agent",
+    "tool-planning",
+    "dag",
+    "execution-plan",
+    "openai"
+  ],
+  "author": "Kirha",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kirha-ai/planner-typescript-sdk"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.10",
+    "@types/bun": "latest",
+    "@types/uuid": "^11.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "json5": "^2.2.3",
+    "openai": "^6.14.0",
+    "uuid": "^13.0.0",
+    "zod": "^4.2.1"
+  }
+}