@elizaos/plugin-local-inference 2.0.0-beta.1 → 2.0.3-beta.2

package/src/services/planner-skeleton.ts

@@ -0,0 +1,175 @@
+/**
+ * Planner (`PLAN_ACTIONS`) skeleton + GBNF wiring for the local-inference
+ * stage.
+ *
+ * The response-handler stage is already constrained — `shouldRespond` is a
+ * three-value enum that the lazy GBNF pins (see
+ * `packages/core/src/runtime/builtin-field-evaluators.ts`). The planner
+ * stage, however, has historically emitted `PLAN_ACTIONS({...})` calls
+ * unconstrained for local backends: the model could hallucinate action
+ * names, drop required parameters, or invent free-form parameter values
+ * outside the registered enum.
+ *
+ * This module is the local-inference-side surface for the same guided-decode
+ * contract the response handler uses:
+ *
+ *   1. `buildPlanActionsSkeleton(actions)` — top-level envelope skeleton
+ *      `{"action": <enum>, "parameters": <free-json>, "thought": <free-string>}`.
+ *      `action` is pinned to the alternation of registered action names and
+ *      collapses to a literal when only one action is exposed.
+ *
+ *   2. `buildPlannerGuidedDecode(actions)` — the full bundle: the skeleton
+ *      above, the precise GBNF (`@elizaos/core`'s `buildPlannerActionGrammar`
+ *      emits one that also pins the array-element enum), and per-action
+ *      `parameters` schemas + sub-skeletons for the engine's optional second
+ *      pass once `action` is committed.
+ *
+ * Why this lives in app-core (not core): the helper is meaningful only to
+ * the local-inference layer — cloud adapters can satisfy the portable `tools`
+ * contract without honoring `responseSkeleton` / `grammar`. Keeping the
+ * wrapper here makes the local-only nature explicit at the import site and
+ * pins the test surface (`__tests__/planner-grammar.test.ts`) next to the
+ * engine that consumes the output.
+ *
+ * GBNF compiler limitation: `compileSkeletonToGbnf` cannot express
+ * per-action parameter discrimination in a single flat skeleton (the spans
+ * are positional; there's no anyOf-with-discriminator branch). We therefore
+ * fall back to the documented two-pass shape — top-level skeleton pins
+ * `action`, the engine drives a second constrained pass against the chosen
+ * action's normalized JSON schema. `buildPlannerParamsSkeleton` (re-exported
+ * from `@elizaos/core`) provides the per-action sub-skeleton.
+ */
+
+import {
+	type Action,
+	buildPlannerActionGrammar,
+	buildPlannerParamsSkeleton,
+	type JSONSchema,
+	normalizeActionJsonSchema,
+	type ResponseSkeleton,
+} from "@elizaos/core";
+
+import {
+	type ElizaHarnessSchema,
+	elizaHarnessSchemaFromSkeleton,
+} from "./structured-output";
+
+/**
+ * The minimal shape this module consumes from an `Action`. Accepting the
+ * structural pick keeps the helper testable in isolation (no handlers /
+ * validators need test doubles).
+ */
+export type PlannerAction = Pick<
+	Action,
+	"name" | "parameters" | "allowAdditionalParameters"
+>;
+
+/**
+ * Bundle of the structure-forcing artefacts the local-inference engine needs
+ * to constrain a `PLAN_ACTIONS` generation.
+ */
+export interface PlannerGuidedDecode {
+	/**
+	 * Top-level skeleton: `{"action": <enum>, "parameters": <free-json>,
+	 * "thought": <free-string>}`. Compiles to a lazy GBNF via
+	 * `compileSkeletonToGbnf` — `action` is the alternation of registered
+	 * action names (or a literal when only one action is exposed).
+	 */
+	responseSkeleton: ResponseSkeleton;
+	/**
+	 * Pre-built GBNF for the top-level envelope. Wins over compiling the
+	 * skeleton (the explicit grammar carries the same alternation as the
+	 * skeleton's enum span — they are byte-equivalent — but the explicit
+	 * grammar is what the cloud-mirroring code path in
+	 * `@elizaos/core`'s `buildPlannerActionGrammar` already produces).
+	 */
+	grammar: string;
+	/**
+	 * Map of action name → normalized JSON Schema for its `parameters` object.
+	 * The engine uses this for the optional second constrained pass once
+	 * `action` is committed. Cloud adapters ignore it; tools carry the
+	 * equivalent (unforced) contract for them.
+	 */
+	actionSchemas: Record<string, JSONSchema>;
+	/**
+	 * Per-action `parameters` skeleton (single-value enums collapse to
+	 * literals; multi-value enums stay as enum spans). Keyed by action name.
+	 * Engines may compile each entry on demand for the second pass.
+	 */
+	paramsSkeletons: Record<string, ResponseSkeleton>;
+	/**
+	 * Eliza harness schema for the top-level envelope — the bundle of
+	 * skeleton + grammar + derived prefill plan. Pass this on
+	 * {@link StructuredGenerateParams.elizaSchema} to engage the
+	 * deterministic-token prefill-plan fast-forward on top of the GBNF
+	 * constrained decode.
+	 */
+	elizaSchema: ElizaHarnessSchema;
+}
+
+/**
+ * Build the top-level `PLAN_ACTIONS` envelope skeleton from the action set
+ * exposed this turn.
+ *
+ * Shape:
+ *   `{"action": <enum>, "parameters": <free-json>, "thought": <free-string>}`
+ *
+ * Returns `null` when no actions are exposed (caller should skip
+ * structure-forcing — there is nothing to constrain `action` to).
+ *
+ * GBNF compiler limitation: `compileSkeletonToGbnf` does not support
+ * anyOf-with-discriminator in a single skeleton — the per-action parameter
+ * shape cannot be expressed positionally. The engine drives a second
+ * constrained pass against {@link PlannerGuidedDecode.actionSchemas} /
+ * {@link PlannerGuidedDecode.paramsSkeletons} once `action` is committed.
+ */
+export function buildPlanActionsSkeleton(
+	actions: ReadonlyArray<PlannerAction>,
+): ResponseSkeleton | null {
+	const result = buildPlannerActionGrammar(actions);
+	if (result === null) return null;
+	return result.responseSkeleton;
+}
+
+/**
+ * Build the full guided-decode bundle for a `PLAN_ACTIONS` generation: the
+ * top-level skeleton, the precise GBNF, the per-action parameter schemas,
+ * and the per-action `parameters` sub-skeletons.
+ *
+ * Returns `null` when no actions are exposed.
+ */
+export function buildPlannerGuidedDecode(
+	actions: ReadonlyArray<PlannerAction>,
+): PlannerGuidedDecode | null {
+	const result = buildPlannerActionGrammar(actions);
+	if (result === null) return null;
+
+	const paramsSkeletons: Record<string, ResponseSkeleton> = {};
+	for (const action of actions) {
+		if (!action.name) continue;
+		paramsSkeletons[action.name] = buildPlannerParamsSkeleton(action);
+	}
+
+	const elizaSchema = elizaHarnessSchemaFromSkeleton({
+		skeleton: result.responseSkeleton,
+		grammar: result.grammar,
+	});
+
+	return {
+		responseSkeleton: result.responseSkeleton,
+		grammar: result.grammar,
+		actionSchemas: result.actionSchemas,
+		paramsSkeletons,
+		elizaSchema,
+	};
+}
+
+/**
+ * Convenience: normalize a single action's `parameters` to a core
+ * {@link JSONSchema}. Re-exported here so callers staying inside the
+ * local-inference module can build per-action constraints without
+ * pulling `@elizaos/core/runtime/...`.
+ */
+export function planActionParameterSchema(action: PlannerAction): JSONSchema {
+	return normalizeActionJsonSchema(action);
+}

package/src/services/providers.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Provider registry.
+ *
+ * Treats every inference source the same way — cloud subscription, cloud
+ * API, Eliza-1 local runtime, paired-device bridge, Capacitor on-device
+ * — each is a `ProviderDefinition` with an `id`, a human label, a set of
+ * supported model slots, and a pluggable `getEnableState()` that inspects
+ * whatever underlying gate controls it (API key presence, subscription
+ * status, env flag, file on disk).
+ *
+ * The cloud-provider status readers are intentionally permissive: they
+ * report what they can introspect without depending on the specific
+ * cloud-plugin internals, and hand off to the existing ProviderSwitcher
+ * UI for actual enable/disable via `configureHref`. That avoids the
+ * "combined enable matrix is an architectural project" problem by making
+ * configuration navigable rather than centralised.
+ */
+import type { ProviderEnableState, ProviderId, ProviderMeta, ProviderStatus } from "@elizaos/shared";
+/**
+ * Runtime provider descriptor. Extends the UI-safe `ProviderMeta` with a
+ * callable `getEnableState()` that inspects env vars, fs, or device-bridge
+ * sockets. Server-side only — UI code reads `ProviderMeta` /
+ * `ProviderStatus` from `@elizaos/shared` instead.
+ */
+export interface ProviderDefinition extends ProviderMeta {
+    /**
+     * Read the current enable state. For cloud providers we inspect env
+     * vars or config fragments; for local we check file presence; for
+     * device-bridge we check connected-device count.
+     */
+    getEnableState(): Promise<ProviderEnableState>;
+}
+export type { ProviderEnableState, ProviderId, ProviderMeta, ProviderStatus };
+/** Resolve which slots have at least one registered handler from this provider. */
+export declare function getRegisteredSlotsForProvider(providerId: string): string[];
+export declare const BUILT_IN_PROVIDERS: readonly ProviderDefinition[];
+export declare function snapshotProviders(): Promise<ProviderStatus[]>;
+//# sourceMappingURL=providers.d.ts.map

package/src/services/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EACX,mBAAmB,EACnB,UAAU,EACV,YAAY,EACZ,cAAc,EACd,MAAM,iBAAiB,CAAC;AAKzB;;;;;GAKG;AACH,MAAM,WAAW,kBAAmB,SAAQ,YAAY;IACvD;;;;OAIG;IACH,cAAc,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAC/C;AAED,YAAY,EAAE,mBAAmB,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,CAAC;AAE9E,mFAAmF;AACnF,wBAAgB,6BAA6B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAO1E;AA+UD,eAAO,MAAM,kBAAkB,EAAE,SAAS,kBAAkB,EAoB3D,CAAC;AAgFF,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CAiBnE"}