# TnsAI as a Language-Action Model (LAM)

Industry writing calls this a **Large Action Model**: an LLM that does not
stop at text, but selects and runs typed actions. In TnsAI that mapping is
`@ActionSpec` methods plus registered tools. The chat loop is LLM + tools,
not a BDI interpreter — see [Roles](../agents/fundamentals/roles.md#bdi-model).

`Belief`, `Desire`, and `Intention` remain as model types. They are
**not** seeded on `AgentBuilder` and `Agent` has no `getBeliefs()` /
`getDesires()` / `getIntentions()`. Optional BDI *planning* goes through
the `CognitiveModel` SPI — see [SPI Reference](spi.md).

```
+-------------------------------------------------------------+
|                 LANGUAGE-ACTION MODEL                       |
+--------------+--------------+--------------+----------------+
|  PERCEPTION  |     GOAL     |     PLAN     |      ACT       |
|   (Belief)   |   (Desire)   |  (Intention) |    (Action)    |
+--------------+--------------+--------------+----------------+
|              LLM + TOOLS + TYPED @ActionSpec                |
+-------------------------------------------------------------+
```

## LAM vs LLM

| Aspect | LLM | LAM (TnsAI) |
|--------|-----|-------------|
| **Output** | Text generation | Typed action execution |
| **Capability** | Language understanding | Tools, HTTP, MCP, local methods |
| **Architecture** | Transformer | LLM + `@ActionSpec` + memory |
| **State** | Stateless | Conversation memory (`MemoryStore`) |
| **Learning** | Pre-trained | Runtime adaptation via tools and memory |

## BDI vocabulary (model types, not Agent overrides)

Application-owned lists, if you keep them yourself:

```java
List<Belief> perceptions = List.of(
    new Belief("Current date: " + LocalDate.now()),
    new Belief("User prefers concise responses"),
    new Belief("Available tools: web search, calculator")
);

List<Desire> goals = List.of(
    new Desire("Provide accurate information", Priority.CRITICAL, "User trust depends on accuracy"),
    new Desire("Complete tasks efficiently", Priority.HIGH, ""),
    new Desire("Maintain user privacy", Priority.HIGH, "")
);

List<Intention> plans = List.of(
    new Intention("Research topic", "Use search tools"),
    new Intention("Summarize findings", "Extract key points")
);
```

Actions are discovered `@ActionSpec` methods on a `Role`:

```java
@ActionSpec(description = "Search the web for information")
public ActionResult searchWeb(String query, ActionResult result) {
    return result;
}
```

## LAM Patterns in TnsAI

### Hierarchical LAM (HLM)

Multi-level planning and execution:

```java
HierarchicalAgentOrchestrator orchestrator = HierarchicalAgentOrchestrator.builder()
    .strategicAgent(plannerAgent)      // Goal decomposition
    .tacticalAgent(coordinatorAgent)   // Sub-task planning
    .operationalAgents(workerAgents)   // Action execution
    .build();

HierarchicalResult result = orchestrator.execute("Build a web scraper");
```

### Large Reasoning Model (LRM)

```java
SelfConsistencyExecutor executor = SelfConsistencyExecutor.builder()
    .llm(client)
    .numPaths(5)
    .aggregation(Aggregation.MAJORITY_VOTE)
    .build();

TreeOfThoughtsExecutor tot = TreeOfThoughtsExecutor.builder()
    .llm(client)
    .evaluator(BranchEvaluator.llm(evalClient))
    .pruning(PruningStrategy.BEAM_SEARCH)
    .maxDepth(5)
    .build();
```

## LAM Capabilities

### 1. Tool Use

Shipped POJO toolkits (`BuiltInTool`) plus HTTP actions via nested
`@WebService` — not a flat `@ActionSpec.endpoint`.

```java
@ActionSpec(
    type = ActionType.WEB_SERVICE,
    webService = @WebService(endpoint = "https://api.weather.com/v1/current")
)
public ActionResult fetchWeather(String city, ActionResult result) {
    return result;
}
```

### 2. Memory Persistence

`Agent.getMemoryStore()` is protected (override the factory). The public
handle is `getAgentMemoryStore()`. `MemoryStore` records conversation
turns with `addMessage` — there is no `store(key, value)` API.

```java
agent.getAgentMemoryStore().addMessage("user", "prefers concise answers");
```

### 3. Multi-Agent Coordination

There is no `A2AClient` type. In-process topologies live under
[Multi-agent](../multi-agent/index.md). Google A2A protocol support is
tracked separately and is not shipped.

### 4. Iterative Refinement

```java
RefinementLoop loop = RefinementLoop.builder()
    .task("Convert Python to TypeScript")
    .completionCriteria(criteria)
    .maxIterations(10)
    .build();
```

## Why LAM Framework?

1. **Beyond chat** — not just conversation, but typed action execution
2. **Enterprise-ready** — Java-native, type-safe
3. **Extensible** — shipped POJO toolkits, custom POJOs, MCP
4. **Observable** — OpenTelemetry
5. **Resilient** — circuit breakers, retry policies, crash recovery

## Getting Started

```java
// AgentBuilder has no .belief(...) (TNS-541)
Agent agent = AgentBuilder.create()
    .llm(new GeminiClient("gemini-2.0-flash"))
    .role(new ResearcherRole())
    .builtInTools(BuiltInTool.WEB_SEARCH_TOOLS)
    .principal(principal)
    .liabilitySink(sink)
    .authorityScope(scope)
    .build();

String result = agent.chat("Research latest AI developments");
```

## References

- [Roles — BDI model](../agents/fundamentals/roles.md#bdi-model)
- [SPI — CognitiveModel](spi.md)
- [8 LLM Architectures Explained](https://aiengineering.beehiiv.com/p/8-llm-architectures-clearly-explained) — industry LAM positioning
- [TnsAI GitHub](https://github.com/TnsAI-Framework/TnsAI) — source
- [BDI Architecture](https://en.wikipedia.org/wiki/Belief%E2%80%93desire%E2%80%93intention_software_model) — theoretical vocabulary