API Reference

This page describes how to obtain a session and the methods it exposes. For command syntax, see Syntax Reference. For architecture details, see Architecture.

Creating a Session

const AgentSystem2 = require('agisystem2');

// Create agent with profile
const agent = new AgentSystem2({ profile: 'manual_test' });

// Create session
const session = agent.createSession();

Configuration Profiles

Profile	Description
`auto_test`	Fast, low memory, for automated tests
`manual_test`	Balanced, for development
`prod`	High precision, for production

See Configuration for full parameter reference.

Session Methods

run(commands)

Execute an array of Sys2DSL commands. Returns environment with bound variables.

// Add facts
session.run(['@f ASSERT Dog IS_A Animal']);
session.run(['@f ASSERT Cat IS_A Animal']);

// Query
const env = session.run(['@q ASK "Is Dog an Animal?"']);
console.log(env.q.truth);  // "TRUE_CERTAIN"

// Get matching facts
const matches = session.run(['@r FACTS_MATCHING ? IS_A Animal']);
console.log(matches.r);  // [{ subject: 'Dog', relation: 'IS_A', object: 'Animal' }, ...]

Theory Management

// Push new theory layer
session.run(['@_ THEORY_PUSH name="experiment"']);

// Add facts to layer
session.run(['@f ASSERT Water IS_A Solid']);  // Hypothetical

// Query in this context
const env = session.run(['@q ASK "Is Water a Solid?"']);
console.log(env.q.truth);  // "TRUE_CERTAIN"

// Pop layer (discards facts)
session.run(['@_ THEORY_POP']);

// Original state restored
const env2 = session.run(['@q ASK "Is Water a Solid?"']);
console.log(env2.q.truth);  // "FALSE" or "UNKNOWN"

Counterfactual Queries

// Ask "what if" questions
const env = session.run([
  '@cf CF "Is ice Water?" | Water TEMPERATURE_AT CelsiusMinus10'
]);
console.log(env.cf.truth);

Common Patterns

Load Theory File

session.run(['@_ LOAD_THEORY medical_knowledge']);

Save Theory

session.run(['@_ SAVE_THEORY my_session']);

List All Facts

const env = session.run(['@facts FACTS_MATCHING ? ? ?']);
for (const fact of env.facts) {
  console.log(`${fact.subject} ${fact.relation} ${fact.object}`);
}

Return Values

Query results include:

Field	Description
`truth`	`TRUE_CERTAIN`, `TRUE_PLAUSIBLE`, `FALSE`, `UNKNOWN`
`confidence`	Numeric confidence (0-1)
`trace`	Provenance trace (optional)

AGISystem2 – API Reference