This document outlines the endpoints that are available when running gactar as a web server (i.e. by passing -w on the command line). The parameters and return interfaces are presented using TypeScript. More detail, along with the actual calls to the server, may be found in web/gactar-web/src/api.ts.
All endpoints are prefixed by /api/.
Important Note: The web API is intended for local use only. It should not be used to expose gactar to the internet. It is not designed for security or to prevent abuse.
Get the version of gactar being run.
(none)
type Version = string
interface VersionResponse {
// The current version tag when gactar was built.
version: Version
}http://localhost:8181/api/version
Result:
{
"version": "v0.11.0"
}Get a list of frameworks supported by the current gactar installation.
(none)
FrameworkInfoResponse which is an array of FrameworkInfo - one entry per framework.
interface FrameworkInfo {
// Name (id) of the framework.
name: string
// Language the framework uses.
language: string
// File extension of the intermediate file.
fileExtension: string
// Name of the executable that was run.
executableName: string
// (Python only) List of packages this framework requires.
pythonRequiredPackages?: string[]
}
type FrameworkInfoList = FrameworkInfo[]
interface FrameworkInfoResponse {
frameworks: FrameworkInfoList
}http://localhost:8181/api/frameworks
Result:
{
"frameworks": [
{
"name": "ccm",
"language": "python",
"fileExtension": "py",
"executableName": "python3",
"pythonRequiredPackages": ["python_actr"]
},
{
"name": "vanilla",
"language": "commonlisp",
"fileExtension": "lisp",
"executableName": "dx86cl64"
}
]
}interface RunOptions {
// List of frameworks to run
frameworks: string[]
// Log level - one of 'min', 'info', or 'detail'
logLevel: string
// Output detailed info about activations
traceActivations: boolean
// Seed to use for generating pseudo-random numbers
randomSeed?: number
}
interface RunParams {
// The text of the amod to run.
amod: string
// The starting goal.
goal: string
// options!
options: RunOptions
}RunResult which includes a list of any issues and a map of FrameworkResult - one entry for each framework that was run.
// Location of an issue in the source code.
interface Location {
line: number
columnStart: number
columnEnd: number
}
interface Issue {
// Severity of the issue.
level: string
// Text of the issue.
text: string
// Location in the code (optional)
location?: Location
}
type IssueList = Issue[]
interface FrameworkResult {
// Name of the model (from the amod text).
modelName: string
// Any issues specific to a framework.
issues?: IssueList
// Intermediate code file (full path).
filePath?: string
// Code which was run.
code?: string
// Output of run (stdout + stderr).
output?: string
}
type FrameworkResultMap = { [key: string]: FrameworkResult }
interface RunResult {
issues?: IssueList
results?: FrameworkResultMap
} http://localhost:8181/api/run
Request payload:
{
"amod": "~~ model ~~\n\n// The name...",
"goal": "[countFrom: 2 5 'starting']",
"options": {
"frameworks": ["pyactr", "ccm", "vanilla"],
"logLevel": "min",
"traceActivations": false
}
}Result:
{
"issues": [
{
"level": "info",
"text": "initial goal is [countFrom: 2 5 'starting']",
"location": null
}
],
"results": {
"ccm": {
"modelName": "count",
"filePath": "/Users/maloney/dev/CogSci/gactar/env/gactar-temp/ccm_count.py",
"code": "# Generated by gactar v0.11.0...",
"output": "2\n3\n4\n5\nend...\n"
},
"pyactr": {
"modelName": "count",
"filePath": "/Users/maloney/dev/CogSci/gactar/env/gactar-temp/pyactr_count.py",
"code": "# Generated by gactar v0.11.0...",
"output": "(0, 'PROCEDURAL', 'CONFLICT RESOLUTION')..."
},
"vanilla": {
"modelName": "count",
"filePath": "/Users/maloney/dev/CogSci/gactar/env/gactar-temp/vanilla_count.lisp",
"code": ";;; Generated by gactar v0.11.0...",
"output": "0.000 GOAL SET-BUFFER-CHUNK GOAL GOAL NIL..."
}
}
}Get a list of the available examples built-in to the server.
(none)
The amod file names which may be used with the /examples/[example_name] endpoint.
// List of example names which are built into the webserver.
type ExampleList = string[]
interface ExampleListResponse {
exampleList: ExampleList
} http://localhost:8181/api/examples/list
Result:
{
"exampleList": [
"addition.amod",
"addition2.amod",
"count.amod",
"semantic.amod",
"topdown_parser.amod"
]
}Get the specified built-in example from the server.
The name of the example (as part of the URL).
The amod code for the requested example. (Note that it is not JSON like the other endpoints - it is straight text.)
http://localhost:8181/api/examples/count.amod
Result:
==model==
// The name of the model (used when generating code and for error messages)
name: count
...
(none)
sessionID integer
The id of the new session.
http://localhost:8181/api/session/begin
Result:
{
"sessionID": 1
}sessionID integer
The id of the session to end.
(none)
http://localhost:8181/api/session/end
Request payload:
{
"sessionID": 1
}interface RunOptions {
// List of frameworks to run
frameworks: string[]
// Log level - one of 'min', 'info', or 'detail'
logLevel: string
// Output detailed info about activations
traceActivations: boolean
// Seed to use for generating pseudo-random numbers
randomSeed?: number
}
interface SessionRunParams {
// The id of the session.
sessionID: number
// The ID of the model to run.
modelID: number
// The initial contents of the buffers.
buffers: string
// Whether to include the generated code as part of the response.
includeCode: boolean
// options!
options: RunOptions
}SessionRunResults which is a map of SessionRunResult - one entry for each framework that was run.
interface SessionRunResult extends Result {
// The id of the session.
sessionID: number
// The ID of the model which was run.
modelID: number
}
export type SessionResultMap = { [key: string]: SessionRunResult }
export interface SessionRunResults {
results: SessionResultMap
}SessionRunResult is just an extension of the FrameworkResult interface to add session & model IDs.
http://localhost:8181/api/session/runModel
Request payload:
{
"sessionID": 1,
"modelID": 42,
"buffers": {
"goal": "countFrom: 2 5 starting"
},
"includeCode": true,
"options": {
"frameworks": ["pyactr", "ccm", "vanilla"],
"logLevel": "min",
"traceActivations": false
}
}Result:
{
"sessionID": 1,
"modelID": 42,
"issues": [
{
"level": "info",
"text": "initial goal is [countFrom: 2 5 'starting']",
"location": null
}
],
"results": {
"ccm": {
"modelName": "count",
"filePath": "/Users/maloney/dev/CogSci/gactar/env/gactar-temp/ccm_count.py",
"code": "# Generated by gactar v0.11.0...",
"output": "2\n3\n4\n5\nend...\n"
},
"pyactr": {
"modelName": "count",
"filePath": "/Users/maloney/dev/CogSci/gactar/env/gactar-temp/pyactr_count.py",
"code": "# Generated by gactar v0.11.0...",
"output": "(0, 'PROCEDURAL', 'CONFLICT RESOLUTION')..."
},
"vanilla": {
"modelName": "count",
"filePath": "/Users/maloney/dev/CogSci/gactar/env/gactar-temp/vanilla_count.lisp",
"code": ";;; Generated by gactar v0.11.0...",
"output": "0.000 GOAL SET-BUFFER-CHUNK GOAL GOAL NIL..."
}
}
}Given a model (amod code), compile and store it on the server. It returns an id to use to reference the model.
interface ModelParams {
// The amod code to load.
amod: string
// The id of the session to load this model in.
sessionID: number
}interface ModelLoadResult {
// The ID of this model to use in other calls to the API.
modelID: number
// The name of the model (comes from the amod code).
modelName: string
// The id of the session.
sessionID: number
} http://localhost:8181/api/model/load
Request payload:
{
"amod": "==model==\nname: count\n ...",
"sessionID": 1
}Result:
{
"modelID": 1,
"modelName": "count",
"sessionID": 1
}