ASTRA API Reference Guide

This reference covers the ASTRA-facing modules in astra-apis. The Agenda, Beliefs and System sections describe ASTRA 2.8.10; the other sections retain their previously documented contracts. It lists actions, terms, formulae and events exposed by module annotations; Java helper classes and internal sensor callbacks are not callable APIs. Separate adapters are covered in Environments, LLM Integration and MAMS.

Using a module

Declare a module inside an agent:

agent Example {
    module Console console;
    module Strings strings;

    plan +!main(list args) {
        console.readString(string Name);
        if (strings.startsWith(Name, "A")) {
            console.println("Hello, " + Name);
        }
    }
}

Each declaration creates an instance associated with that agent. The identifier, such as console, is chosen by you. Classes in astra.lang can use short names; other classes require an import or a fully qualified declaration, such as module astra.util.DB db;.

Kind	Use	Example
Action	Statement; failure fails the calling intention	console.println("Hello");
Term	Expression returning a typed value	int N = prelude.size([1, 2]);
Formula	Guard, condition, query or wait	if (strings.contains("hello", "ell")) { ... }
Event	Trigger for a plan	plan $timer.tick("refresh") { ... }

Action implementations return Java booleans for success or failure; you do not assign these booleans in ASTRA. An output parameter is shown as out T name: pass a typed unbound variable, for example console.readInt(int N);. Term results are shown in the result column. Formulae participate in reasoning, rather than being boolean term expressions. Java object types retain their class names and may require imports.

Indices are zero-based. Typed readers generally cast values instead of converting them, so the stored type must match. Actions that return failure can be handled using Failure Handling; methods that log errors or return null have their own limitations described below.

Module directory

Module	Purpose
Agenda	Named delayed and periodic achievement goals
Beliefs	Adopt and retract beliefs represented as function terms
Console	Console input and output
Debug	Beliefs, events, intention stacks and explanations
Functions	Inspect function terms
Logic	Predicate/function conversion and boolean formulae
Math	Numeric parsing, extrema and random integers
Messaging	Configure message transports
ObjectAccess	Access Java objects through reflection
Prelude	Lists and Java collection conversion
Reflection	Legacy placeholder
Strings	String tests, splitting and replacement
System	Agent lifecycle and runtime management
Goals	Dynamic subgoals and callable metadata
Memory	What an agent remembers of a previous life (weak recovery)
Timer	Periodic events
Logger	Agent logging
Compiler	Runtime parsing and rule construction
ExplanationAccess	Inspect execution explanations
DB	JDBC database access
TupleSpace	Shared named key/value spaces
Logging	Legacy logging wrapper

Core modules

astra.lang.Agenda

Schedules independent top-level achievement goals from function terms. Times are milliseconds: after accepts zero or a positive delay; every requires a positive interval, waits one interval before the first firing and uses fixed-rate scheduling. Names must be nonblank and are local to the owning agent. Scheduling an existing name replaces its future firings. Cancellation succeeds even for an absent name; cancellation and replacement do not withdraw goals already adopted.

Periodic firings are skipped, not queued for later, while a matching achievement goal is queued or running. Matching uses the goal’s predicate name and argument values, not the schedule name, so another schedule or a separately posted matching goal can suppress a firing. Agenda also tracks its own in-flight goal by identity if its arguments are mutated. This is not a lock on all goals with the same name: different arguments can run concurrently, and one-shot schedules do not perform this busy check.

Goal arguments must be ground scalar values (string, int, long, float, double, boolean, char), lists or nested function terms containing only those values. Variables, formulas and arbitrary Java objects are not supported; excessive nesting is rejected. Agenda copies the template when scheduling and copies it again for each firing, so modifying a list in one invocation does not alter later invocations. Agent termination cancels its schedules. This is runtime cleanup, not disk persistence or restart recovery.

module Agenda agenda;
module Console console;
types scheduledWork { formula scan(string); }

plan +!main(list args) {
    agenda.after("initial", 0, scan("hall"));
    agenda.every("periodic", 60000, scan("hall"));
}

plan +!scan(string Room) {
    console.println("scan " + Room);
}

plan +!stopScanning() {
    if (agenda.scheduled("periodic")) {
        agenda.cancel("periodic");
    }
}

Source.

Kind	Signature	Result / behavior
Action	after(string name, int delay, funct goal)	Adopt a goal once after a non-negative delay; replace this agent’s same-named schedule.
Action	every(string name, int interval, funct goal)	Periodically adopt a goal; skip while a matching goal is queued or running.
Action	cancel(string name)	Cancel future firings; already adopted goals continue.
Formula	scheduled(string name)	True while this agent has a schedule waiting for future firings; a one-shot entry is removed when it fires.

astra.lang.Beliefs

Adopts and retracts ordinary beliefs represented as funct values. The function’s name and arguments become the belief predicate’s name and arguments. These actions do not update environment observations or operate a device. For fixed predicates, ordinary +belief(...); and -belief(...); statements remain the simpler choice.

module Beliefs beliefs;
types workState { formula pending(string); }

plan +!main(list args) {
    funct Fact = pending("hall");
    beliefs.adoptBelief(Fact);
    beliefs.adoptBeliefs([pending("kitchen"), pending("office")]);
    beliefs.retractBelief(Fact);
    beliefs.retractBeliefs([pending("kitchen"), pending("office")]);
}

Every entry in a bulk list must be a function term, not a string containing source text or a nested list. The implementation processes entries sequentially and casts each entry to Funct. There is no transaction or rollback: an invalid later entry can fail after earlier entries have already been applied. Retraction targets the supplied predicate, not a wildcard pattern.

Source.

Kind	Signature	Result / behavior
Action	adoptBelief(funct belief)	Add an ordinary belief with this name and arguments.
Action	adoptBeliefs(list beliefs)	Add each function-term entry sequentially.
Action	retractBelief(funct belief)	Drop the supplied ordinary belief.
Action	retractBeliefs(list beliefs)	Drop each function-term entry sequentially.

astra.lang.Console

Reads from Java standard input and writes to standard output. println includes the agent name and a newline; print omits both. Input readers bind their output parameter and require suitable input. readString also prints diagnostic messages in this implementation. There is no read(...) alias: use readString(...).

Source.

Kind	Signature	Result / behavior
Action	println(string string)	Print with agent prefix and newline.
Action	println(funct funct)	Print with agent prefix and newline.
Action	println(formula formula)	Print with agent prefix and newline.
Action	println(int integer)	Print with agent prefix and newline.
Action	println(long value)	Print with agent prefix and newline.
Action	println(float value)	Print with agent prefix and newline.
Action	println(double value)	Print with agent prefix and newline.
Action	println(char value)	Print with agent prefix and newline.
Action	println(boolean bool)	Print with agent prefix and newline.
Action	println(list list)	Print with agent prefix and newline.
Action	println(Object obj)	Print with agent prefix and newline.
Action	print(long value)	Print without prefix or newline.
Action	print(float value)	Print without prefix or newline.
Action	print(double value)	Print without prefix or newline.
Action	print(int value)	Print without prefix or newline.
Action	print(string value)	Print without prefix or newline.
Action	print(boolean value)	Print without prefix or newline.
Action	print(char value)	Print without prefix or newline.
Action	print(formula formula)	Print without prefix or newline.
Action	print(Object obj)	Print without prefix or newline.
Action	printClassName(Object obj)	Print the canonical Java class name.
Action	readInt(out int value)	Read and bind a int value.
Action	readLong(out long value)	Read and bind a long value.
Action	readFloat(out float value)	Read and bind a float value.
Action	readDouble(out double value)	Read and bind a double value.
Action	readString(out string value)	Read and bind a string value.

astra.lang.Debug

Prints internal state for diagnosis. Belief dumps show the ordinary belief base; use an environment adapter’s dump action for its observations. dumpAgentRulesForEvent filters using the event’s exact printed representation. These tools are intended for diagnostics, not as a stable data exchange format. From ASTRA 2.8.1, the module also tells agents when the program is being debugged (see Debugging in VS Code).

Source.

Kind	Signature	Result / behavior
Action	dumpBeliefs()	Print ordinary beliefs.
Action	dumpBeliefsWithPredicate(string predicate)	Print beliefs matching a predicate name.
Action	dumpExplanations()	Print the explanation stack.
Action	dumpAgentRulesForEvent(string ruleEvent)	Print rules matching an event representation.
Action	printStackTrace()	Print the current intention stack.
Action	printEventQueue()	Print pending events.
Formula	active()	True while a debugger is connected to the program.
Formula	isStopped(string name)	True while the named agent is stopped by the debugger.
Event	$debug.attached()	A debugger has connected to the program.
Event	$debug.detached()	The debugger has disconnected; stopped agents have resumed.
Event	$debug.stopped(string name, string reason)	The named agent has stopped in the debugger (reason: breakpoint, step, pause or entry).
Event	$debug.resumed(string name)	The named agent, which had stopped in the debugger, runs again.

astra.lang.Functions

Inspects a funct, such as move("north", 3). functor returns its name and arity its argument count. Typed readers use zero-based argument indices. Numeric readers cast to the requested type; valueAsString uses the primitive value’s string representation. valueType returns the Java class name of a primitive argument and does not handle nested lists or functions.

Source.

Kind	Signature	Result / behavior
Term	functor(funct f)	string — Function-term name.
Term	arity(funct f)	int — Number of arguments.
Term	valueAsInt(funct f, int index)	int — Indexed argument/entry as int.
Term	valueAsLong(funct f, int index)	long — Indexed argument/entry as long.
Term	valueAsFunct(funct f, int index)	funct — Indexed argument/entry as funct.
Term	valueAsDouble(funct f, int index)	double — Indexed argument/entry as double.
Term	valueAsFloat(funct f, int index)	float — Indexed argument/entry as float.
Term	valueAsList(funct f, int index)	list — Indexed argument/entry as list.
Term	valueAsString(funct f, int index)	string — Indexed argument/entry as string.
Term	valueType(funct f, int index)	string — Canonical Java class name of a primitive argument.

astra.lang.Logic

toPredicate exposes a function term as a queryable predicate with the same name and arguments. toFunctor accepts a predicate formula; other formula kinds throw an exception. eval turns a boolean term value into a formula.

Source.

Kind	Signature	Result / behavior
Formula	toPredicate(funct funct)	Query a function term as a predicate.
Formula	eval(boolean value)	Succeed exactly when the boolean is true.
Term	toFunctor(formula formula)	funct — Convert a predicate formula to a function term.

astra.lang.Math

Numeric parsers trim whitespace and use Java parsing rules; malformed or out-of-range input throws an exception. randomInt(bound) requires a positive bound and returns a value from zero inclusive to the bound exclusive. Unbounded randomInt() applies absolute value to a random Java integer: the minimum integer can remain negative. abs has the same minimum-integer overflow limitation. min, max and abs accept integers only.

Source.

Kind	Signature	Result / behavior
Formula	evaluate(boolean value)	Succeed exactly when the boolean is true.
Term	max(int A, int B)	int — Larger integer.
Term	min(int A, int B)	int — Smaller integer.
Term	intValue(string X)	int — Parse an integer string.
Term	longValue(string X)	long — Parse a long string.
Term	floatValue(string X)	float — Parse a float string.
Term	doubleValue(string X)	double — Parse a double string.
Term	randomInt()	int — Random integer; see range limitations above.
Term	randomInt(int bound)	int — Random integer; see range limitations above.
Term	abs(int i)	int — Absolute integer value; see overflow limitation above.

astra.lang.Messaging

Configures transports used by ASTRA’s send statement. Install, configure and start each service once for the JVM. Transport classes must implement astra.messaging.MessageService and be on the classpath. installService logs construction errors but still returns success, so action success alone does not prove installation. Configuration keys depend on the transport. See Agent Communication.

module Messaging messaging;

plan +!main(list args) {
    messaging.installService("local", "astra.messaging.LocalMQService");
    messaging.startService("local");
}

Source.

Kind	Signature	Result / behavior
Action	installService(string id, string clazz)	Install a named message transport.
Action	setProperty(string id, string key, string value)	Configure a named transport.
Action	startService(string id)	Start the named transport.

astra.lang.ObjectAccess

Uses Java reflection on public fields. create requires a public no-argument constructor and returns an Object; a custom module is preferable when a strongly typed result is required. set returns failure for reflection errors, while getters throw. toList requires a Collection field. invoke looks up a method with no parameter types, so it is usable for public no-argument methods; it is not a general overloaded-method dispatcher. The string overload of is uses Java reference equality: use strings.equal(oa.getString(obj, "field"), "value") for content equality.

Source.

Kind	Signature	Result / behavior
Term	create(string classname)	Object — Construct a Java object.
Formula	is(Object object, string fieldName, int value)	Compare a public field with a value; see string caveat.
Formula	is(Object object, string fieldName, long value)	Compare a public field with a value; see string caveat.
Formula	is(Object object, string fieldName, boolean value)	Compare a public field with a value; see string caveat.
Formula	is(Object object, string fieldName, string value)	Compare a public field with a value; see string caveat.
Term	getInt(Object object, string fieldName)	int — Read the field or keyed value as int.
Term	getLong(Object object, string fieldName)	long — Read the field or keyed value as long.
Term	getBoolean(Object object, string fieldName)	boolean — Read the field or keyed value as boolean.
Term	getString(Object object, string fieldName)	string — Read the field or keyed value as string.
Action	set(Object object, string fieldName, int value)	Write a public field.
Action	set(Object object, string fieldName, long value)	Write a public field.
Action	set(Object object, string fieldName, boolean value)	Write a public field.
Action	set(Object object, string fieldName, string value)	Write a public field.
Term	toList(Object object, string fieldName)	list — Convert Java collection values to an ASTRA list.
Action	invoke(Object object, funct call)	Invoke a public no-argument method.
Formula	isType(Object object, string type)	Test Java class membership.
Term	type(Object object)	string — Canonical Java class name.

astra.lang.Prelude

Provides list operations. add, addAt, remove, shuffle, sorting, swap and reverse mutate the supplied list; tail returns a new list. Do not use a head reader on an empty list. Sorting requires mutually comparable values. contains has no boolean or general object overload.

The *ValueFor readers find the first function term with the requested functor in a list, then read argument zero or the supplied index. A missing functor or mismatched type throws. fromASTRAList expects primitive-wrapped values; toASTRAList and toList wrap Java list entries. toObjectArray returns ASTRA term objects, rather than unwrapped Java values. mapToList creates [key, value] pairs; fromMap creates key(value) function terms. toMap accepts function terms or two-element lists and converts keys and values to strings.

module Prelude prelude;

plan +!main(list args) {
    list Values = [3, 1, 2];
    prelude.sort_asc(Values);
    int First = prelude.headAsInt(Values);
    int Count = prelude.size(Values);
}

Source.

Kind	Signature	Result / behavior
Term	headAsString(list list)	string — First entry as string.
Term	headAsInt(list list)	int — First entry as int.
Term	headAsLong(list list)	long — First entry as long.
Term	headAsFloat(list list)	float — First entry as float.
Term	headAsDouble(list list)	double — First entry as double.
Term	tail(list list)	list — New list without the first element.
Action	add(list list, Object object)	Append a value in place.
Action	add(list list, int object)	Append a value in place.
Action	add(list list, long object)	Append a value in place.
Action	add(list list, float object)	Append a value in place.
Action	add(list list, double object)	Append a value in place.
Action	add(list list, char object)	Append a value in place.
Action	add(list list, string object)	Append a value in place.
Action	add(list list, boolean object)	Append a value in place.
Action	addAt(list list, int index, Object object)	Insert at an index in place.
Action	addAt(list list, int index, int object)	Insert at an index in place.
Action	addAt(list list, int index, long object)	Insert at an index in place.
Action	addAt(list list, int index, float object)	Insert at an index in place.
Action	addAt(list list, int index, double object)	Insert at an index in place.
Action	addAt(list list, int index, char object)	Insert at an index in place.
Action	addAt(list list, int index, string object)	Insert at an index in place.
Action	addAt(list list, int index, boolean object)	Insert at an index in place.
Action	remove(list list, int index)	Remove the indexed entry in place.
Term	size(list list)	int — Number of list entries.
Formula	isEmpty(list list)	Test whether the collection is empty.
Formula	contains(list list, string value)	Test membership or substring occurrence.
Formula	contains(list list, int value)	Test membership or substring occurrence.
Formula	contains(list list, long value)	Test membership or substring occurrence.
Formula	contains(list list, float value)	Test membership or substring occurrence.
Formula	contains(list list, double value)	Test membership or substring occurrence.
Formula	contains(list list, char value)	Test membership or substring occurrence.
Formula	contains(list list, funct value)	Test membership or substring occurrence.
Formula	contains(list list, list value)	Test membership or substring occurrence.
Term	stringValueFor(list list, string funct)	string — Read a matching function term’s argument as string.
Term	stringValueFor(list list, string functor, int index)	string — Read a matching function term’s argument as string.
Term	intValueFor(list list, string funct)	int — Read a matching function term’s argument as int.
Term	intValueFor(list list, string functor, int index)	int — Read a matching function term’s argument as int.
Term	longValueFor(list list, string funct)	long — Read a matching function term’s argument as long.
Term	longValueFor(list list, string functor, int index)	long — Read a matching function term’s argument as long.
Term	charValueFor(list list, string funct)	char — Read a matching function term’s argument as char.
Term	charValueFor(list list, string functor, int index)	char — Read a matching function term’s argument as char.
Term	booleanValueFor(list list, string funct)	boolean — Read a matching function term’s argument as boolean.
Term	booleanValueFor(list list, string functor, int index)	boolean — Read a matching function term’s argument as boolean.
Term	objectValueFor(list list, string funct)	Object — Read a matching function term’s argument as object.
Term	objectValueFor(list list, string functor, int index)	Object — Read a matching function term’s argument as object.
Term	floatValueFor(list list, string funct)	float — Read a matching function term’s argument as float.
Term	floatValueFor(list list, string functor, int index)	float — Read a matching function term’s argument as float.
Term	doubleValueFor(list list, string funct)	double — Read a matching function term’s argument as double.
Term	doubleValueFor(list list, string functor, int index)	double — Read a matching function term’s argument as double.
Action	shuffle(list list)	Randomly reorder in place.
Term	valueAsInt(list list, int index)	int — Indexed argument/entry as int.
Term	valueAsLong(list list, int index)	long — Indexed argument/entry as long.
Term	valueAsFunct(list list, int index)	funct — Indexed argument/entry as funct.
Term	valueAsDouble(list list, int index)	double — Indexed argument/entry as double.
Term	valueAsFloat(list list, int index)	float — Indexed argument/entry as float.
Term	valueAsList(list list, int index)	list — Indexed argument/entry as list.
Term	valueAsString(list list, int index)	string — Indexed argument/entry as string.
Term	valueAsBoolean(list list, int index)	boolean — Indexed argument/entry as boolean.
Action	sort_asc(list list)	Sort in ascending order in place.
Action	sort_desc(list list)	Sort in descending order in place.
Action	swap(list list, int i, int j)	Exchange two indexed values in place.
Action	reverse(list list)	Reverse in place.
Term	fromASTRAList(list list)	List — Unwrap primitive entries to a Java list.
Term	toASTRAList(List list)	list — Wrap Java list entries.
Term	toObjectArray(list list)	Object[] — Array of ASTRA term objects.
Term	toString(list list)	string — List representation as a string.
Term	mapToList(Map map)	list — Convert a map to key/value pair lists.
Term	toList(List items)	list — Convert Java collection values to an ASTRA list.
Term	toMap(list list)	Map — Convert entries to a Java string-key/value map.
Term	fromMap(Map<?,?> map)	list — Convert a map to key(value) function terms.

astra.lang.Reflection

Legacy placeholder. addRole currently returns success without changing the agent; it does not implement dynamic role assignment. Use Multiple Inheritance for class reuse and Callable Goals for dynamic goal invocation.

Source.

Kind	Signature	Result / behavior
Action	addRole(string name)	No-op placeholder; always succeeds.

astra.lang.Strings

String comparisons are case-sensitive except equalsIgnoreCase. charAt uses a zero-based Java character index. split takes a Java regular expression, not a literal delimiter, and discards trailing empty tokens. replaceAll also uses Java regular expressions and replacement-group syntax.

module Strings strings;

plan +!main(list args) {
    list Words = strings.split("one,two,three", ",");
    string Clean = strings.replaceAll("room 12", "[0-9]+", "X");
}

Source.

Kind	Signature	Result / behavior
Formula	equal(string source, string target)	Compare string contents.
Formula	equalsIgnoreCase(string source, string target)	Compare without case distinctions.
Formula	startsWith(string text, string pattern)	Test a prefix.
Formula	endsWith(string text, string pattern)	Test a suffix.
Formula	contains(string text, string pattern)	Test membership or substring occurrence.
Term	charAt(string source, int index)	char — Character at the given index.
Term	split(string source, string delimiter)	list — Split using a regular expression.
Term	replaceAll(string source, string regex, string replacement)	string — Replace all regular-expression matches.

astra.lang.System

Manages agents registered through this module and the shared runtime. createAgent creates and schedules an agent; it does not post its main goal. Call setMainGoal separately. Names must be unique. terminateAgent permits the creator or the target itself to terminate the target; terminate affects the current agent. exit ends the JVM and all agents.

Environment configuration

sleep delays the calling action in milliseconds. Prefer Agenda for scheduled goals or Timer for periodic events. Scheduler settings affect the shared runtime. env(variable) returns null for an unset variable. env(variable, fallback) uses the fallback for a missing or blank value and otherwise preserves the string unchanged. envInt(variable, fallback) also falls back for missing or blank values, trims surrounding whitespace before integer parsing, and throws NumberFormatException for malformed or out-of-range integers. getType(name) returns "none" for an unknown agent. deconstruct captures serializable beliefs, name and type, not intentions, pending events or module state; reconstruct is not a complete runtime checkpoint.

The System registry contains agents attached to this module and agents created or reconstructed through it; getAgents() and agentExists() describe that registry, not a discovery service for every possible agent. Attaching the module registers the agent with no creator; creation/reconstruction records the caller as creator. Registry removal notifications forget terminated agents even when termination occurs outside System (for example through Platform.shutdown(...)), and only remove an entry if it still refers to the removed agent object. Ownership controls terminateAgent, but does not imply that terminating a parent automatically terminates its children.

hasChildren can encounter a null owner entry in this implementation; use getChildren() and a list-size check when needed. Rule/event manipulation uses Java runtime objects and is an advanced API.

module System system;

plan +!main(list args) {
    string Host = system.env("ASTRA_HOST", "localhost");
    int Port = system.envInt("ASTRA_PORT", 8080);
    system.createAgent("worker", "examples.Worker");
    system.setMainGoal("worker", []);
}

Source.

Kind	Signature	Result / behavior
Action	skip()	Succeed without an effect.
Term	getAgent()	Agent — Current Java agent object.
Action	fail()	Fail the calling action.
Action	terminate()	Terminate the current agent.
Action	createAgent(string name, string clazz)	Create and schedule a named agent.
Action	setMainGoal(string name, list args)	Post main(args) to the named agent.
Action	terminateAgent(string name)	Terminate an owned agent or self.
Term	getAgents()	list — Names registered with System.
Term	getType()	string — ASTRA class name (current or named agent).
Term	env(string variable)	string — Read an operating-system environment variable.
Term	env(string variable, string fallback)	string — Fallback for missing or blank environment values.
Term	envInt(string variable, int fallback)	int — Parse a trimmed integer; fallback for missing or blank values.
Action	addEvent(Event event)	Enqueue a Java event.
Action	addRule(Rule rule)	Add a runtime rule.
Action	addOrReplaceRule(Rule rule)	Add or replace a runtime rule.
Action	removeRule(Rule rule)	Remove a runtime rule; fails if the agent does not have it (since 2.7.9).
Term	agentRules()	list — Runtime rules as a list.
Term	vocabulary()	string — What the agent can talk about and do: its declared beliefs and goals, its modules’ actions, terms, formulas and events, and its rules, with their descriptions (since 2.7.8).
Term	getType(string name)	string — ASTRA class name (current or named agent).
Term	getAgentsOfType(string type)	list — Names whose classes match or inherit the type.
Term	getChildren()	list — Names of agents created by this agent.
Term	getOwner()	string — Creator name, or “none”.
Formula	hasType(string type)	Test whether an ASTRA class can be loaded.
Formula	hasChildren()	Test for owned agents; see implementation caveat.
Formula	hasOwner()	Test whether this agent has a creator.
Action	exit()	Stop the runtime and exit the JVM.
Action	sleep(int time)	Delay the action in milliseconds.
Term	name()	string — Current agent name.
Action	setSchedulePoolSize(int size)	Set scheduler thread pool size.
Action	setSchedulingStrategy(string strategy)	Load a scheduler strategy class.
Term	currentTimeMillis()	long — Java wall-clock time in epoch milliseconds.
Formula	agentExists(string name)	Test whether a name is registered.
Term	deconstruct(string name)	AgentState — Capture a named agent’s serializable beliefs.
Action	reconstruct(AgentState state)	Create and schedule an agent from captured state.
Term	getNameFromState(AgentState state)	string — Name stored in an AgentState.
Action	setSleepTime(long time)	Set scheduler sleep duration in milliseconds.
Action	displayTimings()	Print per-agent timing statistics.
Action	trace(boolean trace)	Enable or disable agent tracing.
Action	step()	Set the current agent to stepping mode.

astra.lang.Goals

Constructs native dynamic subgoals and reads named outputs. fromString returns a fresh astra.core.GoalInvocation, executed with ASTRA’s invoke statement. Each invocation executes once. Output readers require successful completion, the exact output name and the matching type. callables returns the agent’s callable contracts, including inherited metadata. See Callable Goals and Dynamic Invocation for a complete example and annotation rules.

Source.

Kind	Signature	Result / behavior
Term	fromString(string text)	GoalInvocation — Parse a dynamic goal invocation.
Term	callables()	list — Callable goal descriptors for this agent.
Term	resultAsInt(GoalInvocation call, string name)	int — Read a named completed output as int.
Term	resultAsLong(GoalInvocation call, string name)	long — Read a named completed output as long.
Term	resultAsFloat(GoalInvocation call, string name)	float — Read a named completed output as float.
Term	resultAsDouble(GoalInvocation call, string name)	double — Read a named completed output as double.
Term	resultAsBoolean(GoalInvocation call, string name)	boolean — Read a named completed output as boolean.
Term	resultAsString(GoalInvocation call, string name)	string — Read a named completed output as string.
Term	resultAsChar(GoalInvocation call, string name)	char — Read a named completed output as char.
Term	resultAsList(GoalInvocation call, string name)	list — Read a named completed output as list.
Term	resultAsFunct(GoalInvocation call, string name)	funct — Read a named completed output as funct.

astra.lang.Memory

Since ASTRA 2.6.0. Lets an agent that has been restarted recover from what it remembers of its previous life. This is weak recovery: as with weak migration, the agent’s data survives but its intentions do not. The agent starts afresh, with its initial beliefs, and decides itself what to take back. The memory never changes the agent’s beliefs.

The memory is kept by astra.trace.AgentMemory. Start the JVM with -Dastra.memory=<directory> to keep a memory for every agent. Each agent then has a snapshot, taken periodically and at shutdown, plus a log of changes. These record the agent’s beliefs and its goal set: the top-level achievement goals (!!goal, other than main) that it adopted and that had neither been achieved nor failed. Subgoals are not remembered, because they belong to an intention. When an agent with the same name is created again with the same directory, it receives a $memory.restarted() event. It keeps the memory until it calls memory.recovered(), so if it is restarted again mid-recovery, it gets the same memory again rather than the half-recovered state.

agent Main {
    module Console console;
    module Memory memory;
    module Timer timer;
    module System system;

    types counter {
        formula count(int);
        formula counting(string);
    }

    rule +!main(list args) {
        if (~memory.remembers()) {
            console.println("starting afresh");
            +count(0);
            !!counting("tick");
        }
    }

    rule $memory.restarted() {
        if (memory.believed(count(int n))) {
            console.println("remembered count " + n);
            +count(n);
        }
        foreach (memory.wasPursuing(counting(string name))) {
            console.println("resuming " + name);
            !!counting(name);
        }
        memory.recovered();
    }

    rule +!counting(string name) {
        timer.every(name, 500);
        wait(false);
    }

    rule $timer.tick(string name) : count(int n) {
        -+count(n + 1);
        console.println("count " + (n + 1));
        if (n + 1 == 6) system.exit();
    }
}

Run it with MAVEN_OPTS="-Dastra.memory=memory" mvn compile astra:deploy and stop it after count 3. Run it again with the same directory. It prints remembered count 3 and resuming tick, then continues from count 4. believed and wasPursuing are formulae with one solution for each remembered belief or goal that matches the pattern, so foreach visits every match.

Source.

Kind	Signature	Result / behavior
Event	$memory.restarted()	The agent has a memory of a previous life.
Formula	remembers()	True if the agent remembers a previous life and has not yet called recovered().
Formula	believed(funct pattern)	One solution for each remembered belief that matches the pattern, binding its variables.
Formula	wasPursuing(funct pattern)	One solution for each remembered goal that matches the pattern, binding its variables.
Term	goals()	list — The remembered goals as goal text for the Goals module, for example forall (string g : memory.goals()) { invoke(goals.fromString(g)); }.
Action	recovered()	The agent has recovered; its memory of the previous life is forgotten.

astra.lang.Timer

Schedules periodic events without a sleeping intention. Intervals are positive milliseconds. The first tick occurs after one interval. Reusing a timer name replaces that agent’s existing timer; cancel also succeeds if no timer exists. Timers stop when their agent terminates. Tick handling follows normal event scheduling, so keep handlers short enough for the chosen interval.

module Timer timer;
module Console console;

plan +!main(list args) {
    timer.every("refresh", 1000);
}

plan $timer.tick("refresh") {
    console.println("refresh");
    timer.cancel("refresh");
}

Source.

Kind	Signature	Result / behavior
Action	every(string name, int interval)	Schedule or replace a named periodic timer.
Action	cancel(string name)	Cancel this agent’s named timer.
Event	$timer.tick(string name)	Named periodic tick.

astra.lang.Logger

Wraps Java logging using the agent’s name. Use supported uppercase level strings. Java handler configuration also controls which messages appear. setLogProperties loads a Java logging configuration file. The current INFO() term incorrectly returns "FINEST"; use the literal "INFO" or the info action. The other level terms return their named levels.

module Logger logger;

plan +!main(list args) {
    logger.setLevel("INFO");
    logger.info("agent ready");
}

Source.

Kind	Signature	Result / behavior
Term	OFF()	string — Level name string.
Term	FINEST()	string — Level name string.
Term	FINER()	string — Level name string.
Term	FINE()	string — Level name string.
Term	CONFIG()	string — Level name string.
Term	INFO()	string — Level name string.
Term	WARNING()	string — Level name string.
Term	SEVERE()	string — Level name string.
Action	setLevel(string level)	Set the logger threshold.
Action	setLogProperties(string file)	Load Java logging configuration.
Action	log(string level, string message)	Log a message at the given level.
Action	finer(string message)	Log at FINER level.
Action	fine(string message)	Log at FINE level.
Action	config(string message)	Log at CONFIG level.
Action	info(string message)	Log at INFO level.
Action	warning(string message)	Log at WARNING level.
Action	severe(string message)	Log at SEVERE level.

astra.lang.Compiler

Compiles rules, events and formulae from strings at runtime, so that an agent can add plans while it runs (for example in a missing plan plan). Source is checked as the ASTRA compiler checks it, against the types and modules declared by the agent’s class and its parents, so a compiled rule can use the same beliefs, goals and module actions, terms and formulae as the agent’s own plans. The leading rule or plan keyword is optional. Install compiled rules with System.addRule or System.addOrReplaceRule.

Constants, module event triggers ($module.event), encapsulated goals with inner plans, teleo-reactive functions, learning processes and explain are not supported in rules compiled at runtime. Since 2.7.9, rules compiled at runtime can use modules’ automatic actions and formulae, such as CArtAgO operations. The agent’s classes must have been compiled with ASTRA 2.7.7 or later.

Source.

Kind	Signature	Result / behavior
Action	compileRule(string source, out Rule rule)	Compile a rule; fails if the source does not compile.
Term	compileRule(string source)	Rule — Compile a rule, or null (with the errors printed) if the source does not compile.
Term	ruleErrors(string source)	list — Why a rule does not compile; empty if it compiles.
Term	decompileRule(Rule rule)	string — Render a rule as source.
Term	compileEvent(string source)	Event — Compile an event, or null if it does not compile.
Term	compileFormula(string source)	formula — Compile a formula, or null if it does not compile.

astra.lang.ExplanationAccess

Advanced access to the agent’s explanation store. Uses astra.core.Rule and astra.explanation.Explanation Java objects. Retrieval can be filtered by rule or tag; tag/value methods narrow the match. Check isEmpty and hasRule before reading explanation contents. See Debug for a console dump.

Source.

Kind	Signature	Result / behavior
Term	retrieveAllExplanations(Rule r)	Explanation — Retrieve explanations matching a rule or tag.
Term	retrieveAllExplanations(string tag)	Explanation — Retrieve explanations matching a rule or tag.
Term	latestExplanationUnitFor(Rule r)	Explanation — Retrieve the latest matching explanation unit.
Term	latestExplanationUnitFor(string tag)	Explanation — Retrieve the latest matching explanation unit.
Term	latestExplanationUnitFor(Rule r, string tag)	Explanation — Retrieve the latest matching explanation unit.
Term	latestExplanationUnitFor(string tag, string value)	Explanation — Retrieve the latest matching explanation unit.
Term	latestExplanationFor(string tag, string value)	Explanation — Retrieve the latest matching explanation.
Term	latestExplanationFor(Rule r)	Explanation — Retrieve the latest matching explanation.
Term	fullMatchingExplanation(string tag, Explanation e)	Explanation — Find the full explanation matching a tag and explanation.
Term	sizeOfExplanations()	int — Number of stored explanations.
Term	newID()	int — Allocate an explanation identifier.
Term	getID(Explanation e)	int — Read an explanation identifier.
Term	getRule(Explanation e)	Rule — Read the associated rule.
Formula	hasRule(Explanation e)	Test for an associated rule.
Formula	isEmpty(Explanation e)	Test whether the collection is empty.
Term	getDetail(Explanation e, string tag)	string — Read a tagged explanation detail.

astra.util.DB

JDBC database access. Declare module astra.util.DB db; and add your database’s JDBC driver dependency. getConnection binds a java.sql.Connection; close it when finished. Query builders return astra.util.SQLQuery objects. Supply parallel field/value lists of matching lengths. Raw SQL methods execute the supplied SQL directly; construct and validate SQL for your database deliberately. where adds constraints to a query, get executes a selection and binds a list of rows, and update executes a modification.

Source.

Kind	Signature	Result / behavior
Action	installDriver(string driver)	Load a JDBC driver class.
Formula	tableExists(Connection connection, string table)	Test for a database table.
Action	getConnection(string connectionString, out Connection connection)	Open a JDBC connection.
Action	close(Connection connection)	Close a JDBC connection.
Action	rawUpdateQuery(Connection connection, string sql)	Execute raw modification SQL.
Action	rawSelectQuery(Connection connection, string sql, out list results)	Execute raw selection SQL and bind rows.
Action	where(SQLQuery query, string field, string value)	Add query constraints.
Action	where(SQLQuery query, string field, int value)	Add query constraints.
Action	where(SQLQuery query, string field, long value)	Add query constraints.
Action	where(SQLQuery query, string field, float value)	Add query constraints.
Action	where(SQLQuery query, string field, double value)	Add query constraints.
Action	where(SQLQuery query, string field, boolean value)	Add query constraints.
Action	where(SQLQuery query, string field, char value)	Add query constraints.
Action	where(SQLQuery query, string field, Object value)	Add query constraints.
Action	where(SQLQuery query, list fields, list values)	Add query constraints.
Term	select(string table)	SQLQuery — Construct a selection query.
Term	select(string table, string field)	SQLQuery — Construct a selection query.
Term	select(string table, list fields)	SQLQuery — Construct a selection query.
Term	select(string table, list where_fields, list where_values)	SQLQuery — Construct a selection query.
Term	select(string table, list fields, list where_fields, list where_values)	SQLQuery — Construct a selection query.
Action	get(Connection connection, SQLQuery query, out list results)	Execute a selection query and bind rows.
Term	insert(string table, list fields, list values)	SQLQuery — Construct an insertion query.
Action	update(Connection connection, SQLQuery query)	Execute a modification query.

astra.util.TupleSpace

Shared in-process named key/value spaces. Declare module astra.util.TupleSpace tuples;. Join a space before posting or reading; use hasSpace and hasTuple before typed getters. A post associates a key with a value and can replace that value. These getters read without consuming the entry. Values must match the requested getter type. Space membership is per agent; the data is shared among participants in the JVM.

Source.

Kind	Signature	Result / behavior
Action	join(string id)	Join a named space.
Action	leave(string id)	Leave a named space.
Action	post(string id, string key, Object value)	Store or replace a keyed value.
Action	post(string id, string key, string value)	Store or replace a keyed value.
Action	post(string id, string key, int value)	Store or replace a keyed value.
Action	post(string id, string key, long value)	Store or replace a keyed value.
Action	post(string id, string key, float value)	Store or replace a keyed value.
Action	post(string id, string key, double value)	Store or replace a keyed value.
Action	post(string id, string key, char value)	Store or replace a keyed value.
Action	post(string id, string key, boolean value)	Store or replace a keyed value.
Action	post(string id, string key, list value)	Store or replace a keyed value.
Term	getString(string id, string key)	string — Read the field or keyed value as string.
Term	getInt(string id, string key)	int — Read the field or keyed value as int.
Term	getLong(string id, string key)	long — Read the field or keyed value as long.
Term	getFloat(string id, string key)	float — Read the keyed value as float.
Term	getDouble(string id, string key)	double — Read the keyed value as double.
Term	getList(string id, string key)	list — Read the keyed value as list.
Term	getObject(string id, string key)	Object — Read the keyed value as object.
Term	getChar(string id, string key)	char — Read the keyed value as char.
Term	getBoolean(string id, string key)	boolean — Read the field or keyed value as boolean.
Formula	hasTuple(string id, string key)	Test whether a keyed value exists.
Formula	hasSpace(string id)	Test whether a named space exists.
Term	getSpaceList()	list — List known spaces.

astra.util.Logging

Legacy Java logging wrapper. Declare module astra.util.Logging logging;. Its accepted level names and logger configuration follow Java logging. Prefer astra.lang.Logger for new agents; the legacy wrapper also exposes a finest action.

Source.

Kind	Signature	Result / behavior
Action	setLevel(string level)	Set the logger threshold.
Action	log(string level, string event)	Log a message at the given level.
Action	severe(string event)	Log at SEVERE level.
Action	warning(string event)	Log at WARNING level.
Action	info(string event)	Log at INFO level.
Action	fine(string event)	Log at FINE level.
Action	finer(string event)	Log at FINER level.
Action	finest(string event)	Log at FINEST level.

Related guides

• Working with Lists for list patterns and iteration.

• Creating Multiple Agents for lifecycle examples.

• Creating your own Actions for module annotations and output parameters.

• GUI Support for extending astra.gui.GuiModule with application-specific events.

astra.lang.Agent is a reusable ASTRA agent class, rather than a Java module. AgentState, SQLQuery, timer event classes and the explanation types are supporting objects used by the modules above.