> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dzap.io/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Architecture

> How DZapSDK orchestrates model calls, tools, sessions, logging, and scheduling.

DZap AI uses one runtime (`DZapSDK`) behind four interfaces: SDK, CLI, HTTP, and MCP.
The model decides *what to call*; runtime code decides *what is allowed to execute*.

## Core runtime behavior

* Every ask call requires `metadata.accountInfo[]`
* Metadata is sanitized before prompt injection (`private_key` is excluded)
* Session memory is in-process and keyed by generated `sessionId`

## Model and tool calling

* LLM adapter: `@ai-sdk/openai` with `generateText(...)`
* Default model: `gpt-4o-mini` (`DZAP_OPENAI_MODEL` override)
* Tool choice: automatic
* Step cap: `stepCountIs(25)`
* Retries: `DZAP_MODEL_MAX_RETRIES` (default `2`)
* Timeout: `DZAP_MODEL_TIMEOUT_MS` (default `4500000`)

## Tool exposure pipeline

```text theme={null}
ToolFactory -> EXPOSED_TOOL_NAMES -> SDKToolsRegistry -> DZapSDK -> CLI / HTTP / MCP
```

All exposed tools are wrapped by `SDKTool`, which:

1. validates input with zod when schema is present
2. executes tool code
3. normalizes JSON-string payloads into structured objects
4. returns duration + typed result/error details

## Session logging

Each session captures:

* metadata snapshot
* conversation timeline
* structured tool logs
* summary counters

You can retrieve this through `getSessionHistory(sessionId)` or `GET /sessions/:sessionId/history`.

## Scheduler and persistence

* Storage: SQLite via `better-sqlite3`
* Default DB: `schedules.db` (`DB_PATH` override)
* Statuses: `pending`, `running`, `done`, `error`
* Scheduler loop: runs periodically (60s default from server startup)

On-chain trigger conditions are evaluated with a safe comparison parser (no
`eval`/`new Function`). The action executor is pluggable via
`setScheduleExecutor(...)`; until one is registered, due jobs are left
`pending` and a warning is logged (they are never silently marked `done`).

## End-to-end flow

```text theme={null}
User input
  -> ask()
  -> tool planning + calls
  -> optional interactive confirmation (zap/chain change)
  -> final response + step trace
  -> session log persistence
```

## Related pages

<CardGroup cols={2}>
  <Card title="Safety & Execution" icon="shield" href="/ai/safety-and-execution">
    Interactive gates and execution controls.
  </Card>

  <Card title="SDK-AI" icon="code" href="/ai/sdk-ai">
    API methods and direct tool execution examples.
  </Card>
</CardGroup>