ASTRA API Reference Guide

This guide covers the ASTRA-facing modules in astra-apis for ASTRA 2.6.1. It lists actions, terms, formulae and events exposed by module annotations; Java helper classes and internal sensor callbacks are not callable APIs. The signatures and implementation notes were checked against the 2.6.1 source. 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
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.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.

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.

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.

sleep delays the calling action in milliseconds. Prefer Timer for recurring work. Scheduler settings affect the shared runtime. env returns null for an unset variable. 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.

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) {
    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.
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.
Term	agentRules()	list — Runtime rules as a list.
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

Experimental runtime parsing of rules, events and formulae. Returned objects can be passed to the corresponding System actions. Parse errors may be logged with a null result; the output-parameter compileRule action can return success without binding its output after a parse error. Validate input and results before installing runtime rules. This is not the Maven build compiler.

Source.

Kind	Signature	Result / behavior
Action	compileRule(string source, out Rule rule)	Parse a runtime rule.
Term	compileRule(string source)	Rule — Parse a runtime rule.
Term	decompileRule(Rule rule)	string — Render a runtime rule as source.
Term	compileEvent(string source)	Event — Parse a runtime event.
Term	compileFormula(string source)	formula — Parse a runtime formula.

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.