PowerSolver 2.0 — Quick Reference

The cheat sheet. For the full picture see Concepts Guide.

Top-level JSON skeleton

{
  "problemType": "task-assignment",          // descriptive label
  "collections": {
    "resources": [ /* host items */ ],
    "tasks":     [ /* entity items */ ]
  },
  "variables": [
    {"id": "schedule", "type": "list", "on": "resources", "valueRange": "tasks"}
  ],
  "shadows": [
    {"on": "tasks", "name": "previous", "kind": "previousElement", "source": "schedule"},
    {"on": "tasks", "name": "host",     "kind": "inverseRelation", "source": "schedule"}
  ],
  "derivedShadows": [
    {"on": "tasks", "name": "startTime",
     "sources": ["previous.endTime", "host.startTime"],
     "expression": "previous?.endTime ?? host.startTime"},
    {"on": "tasks", "name": "endTime",
     "sources": ["startTime", "this.duration"],
     "expression": "startTime + this.duration"}
  ],
  "constraints": [
    {"name": "All tasks scheduled", "type": "hard", "rule": "unassigned_count",
     "params": {"inverse_field": "host"}, "weight": 100},
    {"name": "High-priority first", "type": "soft", "rule": "minimize_property",
     "params": {"property": "priority"}, "weight": 1}
  ],
  "config": {"timeoutSeconds": 5}
}

Variable types

Type	Use for	Mandatory fields	Auto-rejected
`list`	Scheduling, routing, sequencing (anything with order).	`id`, `type`, `on`, `valueRange`	`chained` (gone in 2.0)
`basic`	One-to-one assignment without ordering.	`id`, `type`, `on`, `valueRange`	`chainedConfig`, `anchorRange`, `nodeRange`

Built-in shadow kinds

Kind	Returns
`previousElement`	The element before this one in its host's list (or null).
`nextElement`	The element after this one (or null).
`inverseRelation`	The host that owns this element's list.
`index`	0-based position in the host's list.

Expression DSL (for `derivedShadows[].expression`)

Construct	Example
Property path	`previous.endTime`, `host.startTime`, `this.duration`
Null-safe access	`previous?.endTime`
Null-coalesce	`previous?.endTime ?? host.startTime`
Arithmetic	`startTime + this.duration`, `cumulative + this.weight`
Grouping	`(a + b) * c`

Supported value types: Number, Duration, LocalDateTime. Every path used must appear in sources.

Constraint rules (current 2.0 vocabulary)

type (hard/soft) is set per constraint — it's not fixed by the rule. The Typical column is just the common choice.

Rule	Typical	Params	Notes
`unassigned_count`	hard	`{"variable_field": "<var>"}` or `{"inverse_field": "host"}`	Forces every entity to get a value. ALWAYS include one per variable — otherwise the solver "solves" by leaving everything unassigned. Use `variable_field` for basic variables, `inverse_field` for sequence/list mode.
`no_conflict`	hard	`{"fields": ["<var>", ...]}`	No two entities share the same combination of values (no double-booking).
`skill_match`	hard	`{"variable_field","entity_property","value_property"}`	Assigned value must hold the entity's required capability. Requirement may be scalar or a list (value must hold all; empty = anyone).
`resource_exclusivity`	hard	`{"variable_field","entity_property","value_property"}`	Inverse of `skill_match`: a specialised value only hosts an entity that needs it.
`resource_unavailable`	hard	`{"variable_field","slot_field","slot_property","unavailable_property"}`	Resource can't take a slot it's unavailable for.
`protected_slot`	hard	`{"variable_field","value_property"}`	No entity assigned a value whose boolean `value_property` is true.
`no_subject_repeat_per_day`	hard	`{"group_property","category_property","slot_field","day_property"}`	A group can't repeat a category on the same day.
`capacity`	hard	`{"variable_field","capacity_property","load_property"?}`	Summed load per resource ≤ its capacity; penalises excess. `load_property` defaults to 1/entity.
`time_window`	hard	`{"variable_field","value_property","entity_start_property","entity_end_property"}`	Assigned slot time must fall in the entity's `[start,end]`. ISO-8601 / numeric.
`precedence`	hard	`{"slot_field","value_property","depends_on_property"}`	If B depends on A, A's slot must be strictly before B's.
`load_balance`	soft	`{"variable_field": "<var>"}`	Spreads entities evenly across a variable's values.
`minimize_property`	soft	`{"property": "<name>"}`	Minimises the sum of a numeric property (static or derived shadow).
`cost`	soft	`{"variable_field","rate_property","quantity_property"?,"scale"?}`	Minimises Σ(value rate × entity quantity), read through the variable. `scale` normalises money magnitude; both optional, default 1.
`preference`	soft	`{"variable_field","entity_property","value_property"}`	Penalises mismatch between the assigned value's stated preference and the entity. Scalar or list; `weight` = strength.

Sequences and times along a route are expressed with a list variable and derived shadows, not with dedicated rules.

Score shape

0hard/-12soft

Read left-to-right: hard tally first, then soft.
0hard ⇒ feasible. Any negative hard ⇒ infeasible.
The 2.0 score type is HardSoftScore (no medium band).

API — `POST /api/solve`

Request: full §5bis JSON (the skeleton above).

Response (synchronous, completes within the configured timeoutSeconds budget):

{
  "score": "0hard/-6soft",
  "feasible": true,
  "assignments": {
    "R1": ["T1", "T2", "T3"]      // ordered list per host
  },
  "shadows": {                     // present iff the problem has element shadows
    "T1": {
      "previous": null,
      "host":     "R1",
      "startTime": "2026-06-01T08:00",
      "endTime":   "2026-06-01T08:30"
    }
  }
}

Entity-typed shadows (previous / next / host) emit element/host ids. LocalDateTime / Duration / numbers emit their ISO/string form. null stays null.

Error responses

Status	Cause
400	Schema validation failed (missing `collections`, invalid variable type, malformed derived-shadow expression, v1 shape detected).
500	Solver exception or internal error.
501	Feature not implemented (rare — only constraint rules outside the 2.0 vocabulary).

Wizard cheat sheet

Step	What you do
0	AI Intake (optional, the GenAI front door) — answer 5 plain-language questions, confirm PowerAI's interpretation of each (HITL), then Generate. PowerAI emits a full §5bis spec that pre-fills Steps 1–7. Skip to author manually.
1	Load a plan from Excel (Setup sheet: lists, decisions, reference lists, settings; then Fill all steps now or step by step), Download workbook template, ⓘ — or pick a problem type + toggle Sequence Mode on (most schedulers / routers) or off (pure assignment).
2	Define entities — the things being scheduled (with `duration`, `priority`, …). Upload Excel / CSV, Paste, or the workbook banner's Import.
3	Define variables + value-range items (the hosts), and the reference lists (data rules read, never decided). In sequence mode, pick the host fact and apply the default derived-shadow template.
4	Add constraints — at minimum a hard `unassigned_count` for any list variable. Import / Download rules (Excel).
5	(Optional) Pinned assignments — decisions already taken for some items (all their decisions). Never decided for any item → reference list instead.
6	Solver config — `timeoutSeconds` (default 30).
7	Can this work? (red / amber / green, optional quick plan), review the JSON, then Plan it.

Hostnames + ports (production)

Service	Hostname	Port
Solver API	`https://api.planningpowertools.com`	8001
Wizard UI	`https://wizard.planningpowertools.com`	8080
Admin API	`https://admin-api.planningpowertools.com`	8010
AI API	`https://powerai-api.planningpowertools.com`	8060
Orchestrator	`https://orchestrator-api.planningpowertools.com`	8050

Common file paths

What	Where
Solver API source	`D:\PowerProjects\PowerSolver\powersolver-api\`
Wizard source	`D:\PowerProjects\PowerSolver\powersolver-wizard\`
§5bis starter templates	`D:\PowerProjects\PowerSolver\timefold-templates\sequence\`
Test corpus	`D:\PowerProjects\PowerSolver\powersolver-api\test-cases\`
Deploy scripts	`D:\PowerProjects\documentation\installation\`
Documentation	`D:\PowerProjects\PowerSolver\documentation\`