Plan a goal over the acting user's views and rules, without running anything
const url = 'http://localhost:11044/api/v1/admin/kg/plan';const options = { method: 'POST', headers: {'X-Embabel-Api-Key': '<X-Embabel-Api-Key>', 'Content-Type': 'application/json'}, body: '{"goal":"example","inputs":{"additionalProperty":{"type":"example","value":"example"}},"question":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:11044/api/v1/admin/kg/plan \ --header 'Content-Type: application/json' \ --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \ --data '{ "goal": "example", "inputs": { "additionalProperty": { "type": "example", "value": "example" } }, "question": "example" }'Introspects, plans, compiles and quotes. No step runs, no model is called and no source is read, so it is safe to call as the goal is typed — except that a question costs the one model call that writes its goal. Unreachable goals, ties and refusals are 200 answers, not errors.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Optional, and never needed: the call always acts as the signed-in principal. Naming the principal changes nothing; naming anyone else is refused with 403.
Request Bodyrequired
Section titled “Request Bodyrequired”Exactly one of goal, the final Cypher query to answer, or question, the same in plain English (one model call writes its goal); and optionally inputs, keyed by name: {"notes": {"type": "text", "value": "..."}} for text a view reads with ai.fromText, {"account": {"type": "CustomerAccount", "value": "acme.com"}} for one entity of a spine, or {"limit": {"type": "value", "value": "10"}} for the plain parameter it is named after. An input of any other type, or with a blank value, is answered as refused.
A goal (or an English question to write one from) to plan over the acting user’s views and rules, and the typed inputs it starts from. Exactly one of goal and question.
object
The final Cypher query to answer, read-only, written over the facts wanted (projected labels, derived or judged relationships) as if they existed. Not the steps: the planner chooses those.
Typed inputs by name. Absent means none. Name an input after the parameter it is for when more than one could take it.
object
One input to a plan: text a view reads with ai.fromText, one entity of a spine label by its key, or a plain value for the parameter it is named after.
object
text, the name of a spine label of this world, e.g. CustomerAccount, or value.
The text itself, the entity’s key, or the value, coerced to the type the parameter declares.
The same, in plain English, instead of goal: the appliance writes the goal, which costs one model call. A studio planning as the author types sends goal.
Example generated
{ "goal": "example", "inputs": { "additionalProperty": { "type": "example", "value": "example" } }, "question": "example"}Responses
Section titled “Responses”The plan, or why there is none: outcome says which
What planning a goal came to. outcome says which answer this is, and only that answer’s fields are present: planned (reads, steps, compiled, inputs, quote), unreachable (missing, detail, nearest), tie (plans, cost, rivals, toBreak), refused (reasons) or needsInput (needsInput, missing). None is an error: each is the answer. A run adds rows and warnings to a planned answer, or is failed (the plan’s fields, warnings and error, no rows) when the engine answered with an error. Asked as an English question, the answer also echoes the question and the goal written from it, and may be declined (reason, missing).
object
planned: the one Cypher statement the steps and the goal compile to. What a run executes.
tie: the cost the rival plans share, in the planner’s 0..1 units.
unreachable: the planner’s own account of why the goal cannot be reached.
Steps left out of planning, and why; asked as a question, also the facts the goal writer was not offered because nothing describes them. Absent when none were.
failed only: the engine’s error, which is why the run has no rows.
English mode only: the goal written from the question — absent from refused, and from declined or needsInput when none was written.
planned: where each supplied input was bound.
An input the caller supplied, and the step parameter it was bound to.
object
The input’s name, as the caller sent it.
The parameter it binds: a step’s $name, or the goal’s.
unreachable, or declined when that is the reason: the facts no step on offer produces, or the names nothing in the world has (node:Label, relationship:TYPE, property:Label.name). needsInput on a goal: every input fact lacking.
unreachable: for each missing fact, up to five facts the world’s views and rules CAN make, nearest first — same labels, then words of its name or description, then spelling. What the goal could read instead, from the vocabulary plan with no goal and no question lists in full. Absent when none are near.
object
needsInput: the input the goal needs and nobody supplied, the parameter it binds, who reads it, and why.
object
The $name the input binds when supplied; null when none is known or more than one could take it.
The views — or the goal — that read the input; empty when none is known.
text, or the spine label of the identity needed.
Why it is needed, said to the person.
Which answer this is.
tie: the rival plans, each the names of its steps in order. rivals says how they differ, toBreak how to choose.
English mode only: the question asked, echoed.
planned: the engine’s quote for the compiled statement, made without running it.
object
The estimated calls to outside APIs. Null when the statement could not be quoted.
Asked as a question: the model calls made writing the goal — usually one, more when a goal was refused and written again. Zero for a goal the caller wrote, and for a goal reused from an explain of the same question and inputs moments before.
The fewest model calls the run will make, ai.fromText extractions included, plus goalModelCalls. Null when the statement could not be quoted.
The quote rendered as text, or why there is none.
What this quote does not price, by step — a text step’s ai.fromText calls when the statement could not be quoted; the cost gate prices them when the plan runs.
Why the cost gate would refuse this run, or null when it would not (or the statement could not be quoted).
planned: the facts the goal itself reads, as node:Label, edge:From-TYPE->To or input:text.
declined: why no goal this world can reach answers the question.
refused: what to change for the request to plan — an untypable goal, a goal that writes, an input that binds ambiguously, a plan that does not compile.
tie: each rival plan, in the order of plans, with its steps and what only it makes, needs and consults.
One rival plan of a tie: its steps, and what it has that the other plan does not.
object
Facts only this plan makes. A goal that reads one is reached only through this plan.
What only this plan consults beyond the stored graph: api:<label or type> or model:<call or label>.
The plan’s steps the other plan does not use: what makes it a rival.
Facts and inputs only this plan needs. Leaving such an input out leaves only the other plan.
The plan’s steps, in the order they would run, each as a planned step is shown.
One step of a plan, as shown before anything runs: the view or rule, what it adds and needs, what it reaches beyond the stored graph, and its cost.
object
The facts the step makes, as node:Label or edge:From-TYPE->To.
The step’s cost in the planner’s 0..1 units. The plan chosen is the one whose costs sum least.
The saved view or DERIVE rule set this step is.
view, which the compiled statement calls, or rule, which the engine fires when its conclusion is read.
What the step goes beyond the stored graph for: api, model, both, or empty for a stored read. Read off the step itself, not from its cost, which comes from a pluggable heuristic.
The realm that shipped the step. Null for the world’s own.
The facts and inputs the step needs before it can run.
Whether the compiled statement calls this step. False for a rule.
A run of a planned answer only: the rows the compiled statement returned, unchanged. Absent from failed.
object
planned: the chosen steps, in the order they run.
One step of a plan, as shown before anything runs: the view or rule, what it adds and needs, what it reaches beyond the stored graph, and its cost.
object
The facts the step makes, as node:Label or edge:From-TYPE->To.
The step’s cost in the planner’s 0..1 units. The plan chosen is the one whose costs sum least.
The saved view or DERIVE rule set this step is.
view, which the compiled statement calls, or rule, which the engine fires when its conclusion is read.
What the step goes beyond the stored graph for: api, model, both, or empty for a stored read. Read off the step itself, not from its cost, which comes from a pluggable heuristic.
The realm that shipped the step. Null for the world’s own.
The facts and inputs the step needs before it can run.
Whether the compiled statement calls this step. False for a rule.
tie: what would choose one plan — a fact to read in the goal, an input to leave out — or, when nothing a caller sends can, that the world’s steps have to change.
A run only, planned or failed: the engine’s warnings. PROJECTION_* means a projection was declined or incomplete.
English mode, with a goal: true when the goal reads only what the world holds, so no projection was needed.
Example
{ "outcome": "planned", "rivals": [ { "steps": [ { "kind": "view" } ] } ], "steps": [ { "kind": "view" } ]}Neither or both of goal and question were given
A refusal carrying only a human-readable reason.
object
What went wrong, in the terms the caller can act on.
Example generated
{ "error": "example"}No authenticated principal
A refusal carrying only a human-readable reason.
object
What went wrong, in the terms the caller can act on.
Example generated
{ "error": "example"}username names someone other than the signed-in principal
A refusal carrying only a human-readable reason.
object
What went wrong, in the terms the caller can act on.
Example generated
{ "error": "example"}