HTTP API and outputs

cognia_serve exposes one live GPU-backed Mind over HTTP. Requests are serialized with a mutex because all stateful calls operate on the same instance.

Start the server

.\cmake-build-debug\cognia_serve.exe model.cognia networks\trained.bin `
    --network MyNetwork --host 127.0.0.1 --port 8080 --data-dir networks

The network binary is optional. The default bind address is 0.0.0.0, default port is 8080, and default data directory is networks.

For local development, bind to 127.0.0.1. The service currently has no built-in authentication or TLS; do not expose it directly to an untrusted network.

Discover the model

Call /_model at startup and validate sensory, output regions and vocabularies. The API accepts a flat raw sensory vector; it does not apply camera, audio or text cortex preprocessing.

Stateless evaluation

POST /evaluate
Content-Type: application/json

{"input":[0.1,0.9],"iters":8}

/evaluate resets neural state, loads the vector, performs the requested settling iterations and returns top activation, firing state, firing probability, polarization and decoded outputs. Every call is isolated. Use it for independent samples and conventional classification.

The input length must equal sensory from /_model.

Stateful workspace stepping

Load a held input without advancing time:

POST /perceive
{"input":[0.1,0.9]}

Then advance the living mind:

POST /step
{"steps":4,"count_fires":true}

/step runs the full Mind::step path, including workspace behavior, and pumps output adapters after each step. Signal-output hysteresis therefore persists across calls. steps is clamped to 1..10000. With count_fires, the response also contains fire counts over the requested interval.

Stateful raw sequence feed

POST /feed
{"input":[0,1,0],"steps":3}

/feed preserves recurrent and delay state but uses raw propagation matching sequential reservoir training. It omits the additional workspace/adaptation loop of full stepping. Use it for token-by-token reservoirs and sequence examples whose trainer uses the same path. steps is clamped to 1..1000.

Do not mix /feed and /step casually: they have different semantics.

Reset

POST /reset
{}

Reset clears activity and resets the stochastic generator. Use it at sequence/trial boundaries.

Save and load

POST /save
{"path":"experiment.bin"}

POST /load
{"path":"experiment.bin"}

Paths are confined to --data-dir. Absolute paths and .. traversal are rejected. Binary state must match the topology dimensions created from the source model.

Declared output responses

Responses contain an outputs array. The exact fields depend on type:

• signal: name, type, level and active boolean;
• text: name, decoded literal/token, confidence and index;
• classification: name, class label/index, confidence/probabilities based on logits.

If the model declares no supported output, the server creates a fallback awareness signal over the top region.

Errors and concurrency

Malformed JSON, missing arrays, dimension mismatch and unsafe paths return a JSON error with an HTTP 4xx status. Runtime failures return 5xx. Calls are serialized, but clients still need an application-level session policy: two users calling the stateful endpoints share one mind and can alter each other's context. Run one process per independent session when isolation is required.