WOLF

Historically, WOLF has meant the Workflow Orchestration Language Framework. As the project evolves, WOLF also names the Workflow Orchestration Learning Framework: a philosophy and runtime direction for agents that learn from workflows, tools, users, environments, and their own operational traces.

Most agent systems give models tools.

WOLF gives agents worlds.

WOLF is not merely an agent harness. It is a learning framework: an infrastructure substrate that agents, harnesses, workflows, and users can inhabit while solving tasks. It provides agents with curated action spaces, memory, context management, knowledgebases, toolboxes, universes/actionboxes, gateway runtimes, and shared visual workspaces so they can interact with environments rather than only call tools.

The core design bet is inspired by Richard Sutton's Bitter Lesson: durable progress comes less from hand-encoding every decision and more from building general systems that can learn from computation, search, feedback, and interaction with environments. WOLF therefore emphasizes agents that can explore, discover, exploit, evaluate, remember, and improve their own strategies over time.

WOLF is not competing to be the best wrapper around today's agents.

WOLF is trying to become the environment in which tomorrow's agents learn how to become better agents.

Much of the repository still uses WOLF terminology in code, prompts, configuration, commands, and documentation. In practice, this repository should be understood as the active development branch of the WOLF-style runtime.

What is WOLF?
Why WOLF is Different
Levels of Agency
WOLF Philosophy
Core Mental Model
Repository Highlights
Quick Start
Running the Application
Interactive CLI Usage
Gateway / TUI Workflow Runtime
Frames / Dashboard Webapps
Architecture Overview
Structured Actions
Infrastructure Layer
Memory and Context Management
Universes / ActionBoxes
Knowledgebases, Toolboxes, and Vector Stores
Sessions, Persistence, and Resume
Configuration
Prompt, Rules, and Behavior Files
Developer Notes
Living Documentation
License

What is WOLF?

WOLF provides a composable learning runtime for agentic workflows. Instead of treating an LLM as a text generator attached to tools, WOLF treats an agent as an actor inside an infrastructure-rich environment. The active workflow expects agents to emit validated JSON actions. Those actions are discovered dynamically from the framework, validated with Pydantic models, executed through the local infrastructure layer, and routed back to the user, system, another agent, the GUI/VUI, or an external sandboxed universe.

WOLF can be used as a harness, but it is broader than a harness. A harness usually wraps an agent so it can perform a task. WOLF provides the environment, memory, action space, workflow substrate, evaluation traces, and shared work surfaces that let agents and harnesses improve how tasks are performed.

The framework supports:

Interactive human-agent workflows through CLI, TUI, GUI, and gateway modes.
Structured agent actions validated against dynamically discovered schemas.
Action metadata such as purpose, expectations, and yield_motion_to, allowing intent, success criteria, routing, and policy traces to be inspected after execution.
Session persistence and resume with workflow snapshots.
Memory and context management for long-running sessions.
Knowledgebases backed by vector stores and metadata inventory.
Toolboxes for discoverable and executable tools.
Universes / ActionBoxes as external or nested sandbox environments.
VUI / shared visual workspace support through the GUI, dashboards, visual context, and permissioned live capture.
Workflow selection through the root ./wolf application launcher.
Agent-to-agent routing when worker agents are configured.

Why WOLF is Different

Most agent frameworks today are built around a simple pattern:

LLM + tools + prompts + orchestration glue

That pattern is useful, but it is not enough.

It gives the agent hands, but not a world.
It gives the agent tools, but not a developmental loop.
It gives the agent logs, but not a structured memory of intent, expectation, outcome, reward, and policy.

WOLF starts from a different premise:

Agent + curated action space + environment + memory + evaluation + self-improvement loop

Agents will not become truly powerful merely by being connected to more tools. They become more powerful when they can interact with environments, observe consequences, evaluate strategies, remember what worked, revise their policies, and recursively reduce the impedance between intention and solution.

The difference matters.

Actions, not just tools

WOLF agents have actions instead of merely tools.

A tool is an executable capability.
An action is an expression of intent.

A WOLF action includes:

action: what the agent intends to do,
payload: the operational parameters,
purpose: why the agent is doing it,
expectations: what successful execution should produce,
yield_motion_to: who or what should act next.

That difference is profound.

A sequence of WOLF actions is not just an execution log. It is a decision tree. It is a strategy trace. It is policy made visible. It reveals what the agent tried, why it tried it, what it expected, what actually happened, and where the approach succeeded or failed.

Because actions carry purpose and expectations, they can be evaluated. Because they can be evaluated, they can be scored. Because they can be scored, they can become reward signals. Because they can become reward signals, agents can compare strategies, practice through self-play, and improve.

Learning from interaction with environments

WOLF is built with Sutton's Bitter Lesson in mind. Instead of relying primarily on encoded task-specific decisions, WOLF tries to provide agents with environments they can interact with and learn from.

With a well-curated action space, agents can do more than call tools. They can:

explore an environment,
discover available capabilities,
exploit known strategies,
compare alternative approaches,
evaluate outcomes against explicit expectations,
preserve useful experience as memory or wisdom artifacts,
improve policies, playbooks, workflows, and action selection over time.

This is especially important for design and discovery tasks, where success may require stepping outside the current method, finding a new representation, or inventing a better policy rather than following a fixed recipe.

Self-play and policy improvement

Because actions record purpose and expectations, completed task traces can be evaluated by humans, programs, or LLM-as-judge evaluators. A workflow can be scored against objectives such as:

task success,
token use,
latency,
number of actions,
safety margin,
reversibility,
quality of intermediate artifacts,
user satisfaction,
robustness across environments,
reduction of future impedance.

That score can become a reward signal. The first successful strategy becomes a baseline. The agent can then re-run the task, try an adjusted strategy, compare the result, and keep the better policy. Over time this enables reinforcement-learning-inspired self-play without requiring immediate model weight updates: improvement can occur through memory, policies, playbooks, action-space curation, context strategies, and workflow revisions.

VUI: the shared working world

The Wolf GUI/VUI is not just a user interface. It is the first concrete expression of WOLF's shared-world model.

If the user can see it, the agent can request permission to see it.
If the user can touch it, the agent can request a safe, auditable way to touch it.

The VUI turns visual state into shared operational state. Dashboards, browser surfaces, annotations, captures, artifacts, workflow events, and user intent become part of the agent's environment.

This is not ordinary browser automation. It is not just chat with screenshots. It is the beginning of a shared human-agent workspace where perception, action, evaluation, and learning happen in the same loop.

Infrastructure for agents and harnesses

WOLF is therefore best understood as a framework that provides infrastructure to agents and harnesses:

an action schema language,
workflow orchestration,
local and remote environments,
memory and context systems,
KB/TB/Universe composition,
GUI/VUI shared workspace state,
capture artifacts and visual grounding,
session persistence,
evaluable traces.

A harness can run inside WOLF. An agent can use WOLF. A workflow can be evaluated by WOLF. WOLF is the learning substrate that makes those interactions inspectable, repeatable, and improvable.

Levels of Agency

WOLF is designed around a developmental view of agency. The question is not only:

Can the agent call a tool?

The deeper question is:

How much can the agent participate in improving the conditions of its own future success?

The levels are not product claims or rigid boxes. They are maturity milestones: a ladder from passive information access toward agents that diagnose themselves, improve their policies, master environments, and discover new ways to act.

Knowledge → Communication → Operation → Tool/Workflow Management → Diagnostics → Self-Play → Environment Mastery → Extrapolation

Level	Name	Meaning
0	Knowledge	The agent can retrieve, ingest, and use information.
1	Communication	The agent can clarify, explain, negotiate task contracts, coordinate, and route information.
2	Operation	The agent can act through tools, files, APIs, workflows, sandboxes, dashboards, and environments.
2.5	Tool and Workflow Management	The agent can select, compare, document, revise, compose, and improve the means of operation.
3	Self-Awareness and Diagnostics	The agent can inspect failures, uncertainty, action-space gaps, perception errors, and strategy quality.
3.3	Self-Play and Policy Improvement	The agent can compare strategies, evaluate reward, practice in sandboxes, and improve policies over repeated attempts.
4	Environment Mastery	The agent can compose, configure, project, and improve the environments in which it acts.
5	Extrapolation	The agent can discover new abstractions, workflows, evaluation regimes, and forms of agency beyond the original designer's frame.

Most tool-use harnesses aim at Level 2: operation.

WOLF is built to make Level 3 and beyond possible. That requires more than tools. It requires evaluable action traces, memory, context, universes/actionboxes, visual grounding, workflow continuation, permissioned shared workspaces, self-play, and policy improvement.

This is why WOLF is a learning framework rather than just a runner. It is infrastructure for developmental agency.

For the full maturity model and philosophy, see philo.md.

WOLF Philosophy

Beyond the runtime described in this README, WOLF is also a philosophy for building self-evolving agentic systems.

Current agent frameworks often focus on connecting LLMs to tools, prompts, skills, and workflow glue. WOLF aims to go further: it asks how agents can learn from the environments in which they act, preserve reusable operational wisdom, diagnose their own failure modes, improve their policies, practice through self-play, and co-evolve with their infrastructure.

This philosophy deliberately treats environments as teachers. Users, files, tools, universes, dashboards, captures, failures, rewards, and workflow traces all become part of the curriculum. The framework is designed so agents can eventually evaluate not only what answer they produced, but which action strategy produced it and whether a better strategy can be discovered.

The guiding thesis is:

Agency is the recursive reduction of impedance to solution search.

In this view, an agent is not only a task executor. It is a participant in the improvement of the workflows, tools, memories, evaluations, and environments that make future solutions easier to find.

The public living philosophy document is here:

philo.md — WOLF as an open invitation to build self-evolving agentic systems.

We welcome revisions, critiques, missing failure modes, new capability levels, safety concerns, implementation experiments, and alternative framings.

Core Mental Model

At runtime, the system is organized around a few key concepts:

Concept	Meaning
Agent	An LLM-backed actor, usually an `OpenAIAgent`, that receives workflow context and emits JSON actions.
User	The human participant in the workflow.
System	The local sandbox/interface through which actions are executed.
Infrastructure	The runtime object that exposes agents, objects, managers, history, context, memory, universes, KBs, and TBs.
Action	A Pydantic model subclassing `AgentAction`. A structured expression of intent containing operational parameters plus purpose, expectations, and turn-routing metadata.
Workflow	The orchestration loop that routes turns between users, agents, workers, and the system.
Universe / ActionBox	A sandboxed environment that can host knowledgebases, toolboxes, and executable actions.
KnowledgeBase / KB	A searchable document or memory store, typically backed by vector storage.
ToolBox / TB	A collection of discoverable and executable tools.
Memory Manager	Stores and recalls durable memory fragments and summaries.
Context Manager	Maintains the compact active context sent to agents.
Chat Manager	Stores chat history, console output, and snapshot state.

A useful high-level flow is:

User objective / environment state
  -> Workflow
  -> BaseInfrastructure
  -> ContextManager / MemoryManager / ChatManager
  -> Agent prompt with allowed action schema
  -> Agent emits JSON action with payload + purpose + expectations
  -> Action is validated and executed through infrastructure
  -> Outcome is recorded as trace / memory / artifact
  -> Workflow routes the next turn
  -> Trace can be evaluated for policy or strategy improvement

Repository Highlights

./wolf                                      # Main CLI application wrapper
README.md                                  # This document
philo.md                                   # Public living philosophy for WOLF self-evolving agents
app.md                                     # Broad living architecture notes
wisdom.md                                  # Index of focused wisdom nuggets
wisdom_nuggets/                            # Source-grounded development notes
runners/interactive.py                     # Traditional interactive launcher
config/defaults/inference_engine.py        # Default LLM/provider configuration
config/session/default/params/inputs.py    # Default session parameters
framework/cli/                             # Real ./wolf CLI application implementation
framework/utils/config_tools.py            # Session construction and resume helpers
framework/utils/frame_dashboard.py         # FRAME dashboard run/deploy utility used by ./wolf frame
framework/infrastructure/                  # Runtime infrastructure, chat, memory, context
framework/workflows/                       # Workflow base classes, action models, active workflows
framework/workflows/custom_workflows/gateway_action_workflow.py  # Async websocket workflow/action runtime
framework/workflows/agent_actions/         # Dynamically discovered workflow actions
framework/agentic/                         # Agent implementations
framework/data_store/                      # Vector store layer
framework/knowledgebase/                   # KnowledgeBase implementations
framework/tooling/                         # Tools and ToolBox implementations
framework/universes/                       # Universe / ActionBox support
framework/gateway/                         # Gateway client/server/TUI support
framework/ui/                              # UI-related clients
framework/gui/                             # Wolf GUI / VUI shared visual workspace
FRAMEs/dashboards/                         # Local FRAME webapps for GUI dashboard panels
framework/orchestration/                   # Adjacent or evolving orchestration subsystem
sessions/                                  # Example launch/session configs
wf_workspace/                              # Runtime session directories, snapshots, stores

Quick Start

1. Clone the repository

git clone git@github.com:lanl/wolf.git
cd wolf

2. Install the environment

WOLF can be installed using several Python environment workflows. The older Conda-only setup is still supported, but the repository now includes pyproject.toml, so uv, pip, and other PEP 517/518-compatible tools can be used as well.

Python 3.13 or newer is recommended unless your branch or deployment environment specifies otherwise.

2.1 Option A: Using `uv` recommended for local development

If you have uv installed, this is usually the fastest way to create and manage a local development environment:

uv sync

Then run commands through uv:

uv run ./wolf --help
uv run ./wolf doctor
uv run ./wolf

The root ./wolf wrapper may already invoke uv internally depending on the current checkout, so in many cases this is enough:

./wolf

If you need to include optional dependency groups, use the project/team convention for this repository, for example:

uv sync --all-extras

2.2 Option B: Using `pip` with a virtual environment

Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate

Install the project from pyproject.toml:

pip install -e .

If the project defines optional extras, install the ones you need, for example:

pip install -e '.[dev]'

Then launch the app:

./wolf

or:

python -m framework.cli.wolf_app --help

2.3 Option C: Using Conda / Anaconda

The historical setup used Conda and is still a valid option, especially on shared systems where Conda is the standard environment manager.

conda create -n wolf python=3.13
conda activate wolf

Then install the project:

pip install -e .

If you are working from an older checkout or need to manually install the legacy dependency set, use:

pip install dotenv searxng_wrapper rich openai funkybob tiktoken pdfplumber nbformat alive_progress prompt_toolkit chromadb fastapi dill

If the repository-provided environment.yml is the preferred team workflow for your branch, you can instead create the environment from it:

conda env create -f environment.yml
conda activate wolf

2.4 Option D: Existing managed environment

On managed systems, shared development machines, or containerized deployments, you may already have a compatible Python environment. In that case, activate the environment according to local site instructions, then install the project if needed:

pip install -e .

Verify the CLI is available:

./wolf --help
./wolf doctor

3. Configure environment variables

Create a local .env file from the sample if available:

cp sample.env .env

Configure inference settings for one default LLM such as:

INFERENCE_HOST_ADDRESS=...
INFERENCE_HOST_PORT=...
LOCAL_API_KEY_VAR=...
API_VERSION=...
LLM_MODEL=...
LLM_CAPABILITIES=...

The default loader also supports multiple LLMs from .env. Use indexed LLM_N_* variables to create one agent per entry. The first entry becomes the main agent and later entries become worker agents. Missing per-entry provider fields inherit the single/default provider settings above.

LLM_1_NAME=main
LLM_1_MODEL=model-a
LLM_1_HOST_ADDRESS=https://example-llm-host
LLM_1_LOCAL_API_KEY_VAR=LOCAL_API_KEY
LLM_1_API_VERSION=v1
LLM_1_CAPABILITIES=['text','tool']

LLM_2_NAME=worker
LLM_2_MODEL=model-b
LLM_2_HOST_ADDRESS=https://example-llm-host
LLM_2_LOCAL_API_KEY_VAR=LOCAL_API_KEY
LLM_2_API_VERSION=v1
LLM_2_CAPABILITIES=['text']

As an alternative, set LLMS_JSON to a one-line JSON object or list. LLMS_JSON takes precedence over indexed LLM_N_* entries when set.

LLMS_JSON='{ "main": {"model": "model-a", "host": "https://example-llm-host", "api_key_var": "LOCAL_API_KEY", "api_version": "v1", "capabilities": ["text", "tool"]}, "worker": {"model": "model-b", "host": "https://example-llm-host", "api_key_var": "LOCAL_API_KEY", "api_version": "v1", "capabilities": ["text"]} }'

or provide a path to a json file containing configuration for the different llms (refere to sample_llm_config.json) using the variable "LLMS_JSON_FILE"

LOCAL_API_KEY_VAR and per-entry LLM_N_LOCAL_API_KEY_VAR values should name the environment variable that contains your actual inference API key. For example, if:

LOCAL_API_KEY_VAR=LOCAL_API_KEY

then .env or your shell environment should also contain:

LOCAL_API_KEY=your_api_key_here

Default inference configuration is built in:

config/defaults/inference_engine.py

4. Configure SSL certificates if needed

On Linux systems such as Rocinante, add to your shell RC file:

export CURL_CA_BUNDLE="/etc/ssl/ca-bundle.pem"
export SSL_CERT_FILE="/etc/ssl/ca-bundle.pem"

On macOS, standard system certificates may work with:

export CURL_CA_BUNDLE="/etc/ssl/cert.pem"
export SSL_CERT_FILE="/etc/ssl/cert.pem"

For Homebrew OpenSSL, one of these may be appropriate:

export CURL_CA_BUNDLE="/usr/local/etc/openssl@3/cert.pem"
export SSL_CERT_FILE="/usr/local/etc/openssl@3/cert.pem"

or:

export CURL_CA_BUNDLE="/usr/local/etc/openssl/cert.pem"
export SSL_CERT_FILE="/usr/local/etc/openssl/cert.pem"

Running the Application

The preferred entrypoint is the root ./wolf executable.

./wolf

Plain ./wolf launches an interactive CLI session using FastTurnBasedWorkflow by default. The legacy TurnBasedWorkflow remains available via --workflow TurnBasedWorkflow.

You can also use the newer CLI command tree:

./wolf --help
./wolf cli --dry-run --explain
./wolf cli --workflow FastTurnBasedWorkflow
./wolf cli --workflow TurnBasedWorkflow
./wolf cli --resume last
./wolf cli --config sessions/example_cli_session.json
./wolf workflows list
./wolf actions list --limit 10
./wolf sessions list
./wolf sessions inspect last
./wolf config print --config sessions/example_cli_session.json
./wolf config validate --config sessions/example_cli_session.json
./wolf frame run --host 127.0.0.1 --port 8012
./wolf frame deploy ./FRAMEs/dashboards/view_files --copy ./FRAMEs/dashboards/dashboard2 --host 127.0.0.1 --port 8013
./wolf doctor

The traditional Python launcher still exists:

python runners/interactive.py

Interactive CLI Usage

During an interactive session, user input is routed through the active workflow and infrastructure layer.

Useful built-in commands include:

\>show chat
\>show history
\>show context
\>show ctx

Terminal commands can be issued with:

!> ls -la
!> pwd

If worker agents are configured, route input to a worker with:

@worker_name your message here

Exit commands include:

exit
quit
/exit
/quit
/bye

Clear commands include:

clear
cls
/clear

Gateway / TUI Workflow Runtime

The gateway path now supports real WOLF structured-action execution over websocket sessions. Instead of sending websocket chat directly to OpenAIAgent.get_chat_response_async(...), the gateway creates a per-session WOLF runtime and routes chat through GatewayActionWorkflow.

Important files:

framework/pack/gateway.py                                  # FastAPI gateway, auth, websocket transport, runtime registry
framework/workflows/custom_workflows/gateway_action_workflow.py  # Async action workflow used by gateway sessions
framework/ui/tui_client.py                                 # Terminal client with workflow-event rendering

Runtime split

The gateway remains a transport/session layer. It owns:

authentication and account/session ownership;
websocket connection management and event fanout;
runtime bundle creation and lookup;
one asyncio.Lock per session to serialize mutable workflow state.

GatewayActionWorkflow owns WOLF orchestration semantics:

user-message ingestion into workflow history;
prompt composition using compact context, action schema, infrastructure description, behavior, and workflow rules;
structured action generation using async structured-output APIs when available;
synchronous JSON-format fallback through an executor/thread when needed;
action normalization, validation, execution, history updates, and snapshots;
turn policy for single_step and wolf_loop modes.

Each gateway session stores a runtime bundle roughly shaped as:

{
    "agent": main_agent,
    "wf": GatewayActionWorkflow(...),
    "infra": BaseInfrastructure(...),
    "managers": {"chat": ..., "memory": ..., "context": ...},
    "config": agent_config,
    "session_dir": "wf_workspace/gateway/<account>/session_<id>",
    "lock": asyncio.Lock(),
}

Gateway action policies

Gateway action exposure is policy-driven. The default policy is intentionally conservative:

safe — send_message, read_file, check_context_utilization, list_memory_categories
write — safe policy plus write_file
dev — write policy plus guarded run_syscall

You can update a gateway session from the TUI with commands such as:

/config agent params action_policy='dev'
/config agent params action_policy='write'
/config agent params enable_syscall=true syscall_max_timeout=5

run_syscall is still guarded at execution time. By default dev mode blocks shell=True, shell composition/metacharacters, dangerous commands, and commands outside a small allowlist such as pwd, ls, cat, head, tail, grep, find, wc, and echo.

Websocket workflow events

For websocket chat messages, the gateway now emits:

user_echo — immediate UI echo of user input;
workflow_status — lifecycle updates such as received, thinking, and done;
workflow_action — normalized action payload selected by the agent;
workflow_result — action result summary and any appended history delta;
workflow_error — validation or execution errors safe for transport;
legacy system, error, ping, and pong events remain supported.

The TUI renders send_message workflow results as assistant chat bubbles and renders non-chat actions/results as action/result panels.

Join-session participant scaffold

The gateway websocket layer now supports multiple participants attached to the same session. Each connection may provide a participant_id, participant_role, and client_type; the gateway emits presence events and can broadcast participant_message events.

A first CLI join command is available:

./wolf join-session   --gateway http://127.0.0.1:8000   --account-id <account_id>   --session-id <session_id>   --token <token>   --participant-id sad_chaplygin_clone

This is currently a message-level participant bridge. It is the foundation for later agent-only joined workflows, clone testing, benchmarking, and context-transfer/self-evolution experiments.

Gateway hardening and diagnostics

Recent gateway hardening adds several operational safeguards:

Policy visibility: the gateway emits a policy_resolved event before workflow execution so clients can see the effective policy and action allowlist.
Policy introspection: GET /sessions/{session_id}/policy returns configured policy values plus resolved action names and execution guardrails.
Participant introspection: GET /sessions/{session_id}/participants returns known participant metadata for a gateway session.
Secret redaction: gateway parameter/config responses and TUI displays redact sensitive fields such as api_key, token, password, secret, and authorization.
Fallback schema hygiene: GatewayActionWorkflow avoids appending the action schema twice in non-structured-output fallback paths; the workflow owns the effective restricted schema.
Smoke testing: scripts/gateway_smoke.py can log in, configure a session, inspect policy, connect by websocket, send a message, and assert workflow events.

Example smoke-test shape:

python scripts/gateway_smoke.py \
  --username max \
  --password '' \
  --policy dev \
  --host-address https://example-llm-host \
  --api-key "$LOCAL_API_KEY" \
  --model gpt-5.4-nano \
  --api-version v1 \
  --message "What is the current working directory? Use run_syscall with command pwd, shell false, timeout 5."

Frames / Dashboard Webapps

Frames are local webapps/backends that can be launched as display surfaces for WOLF GUI dashboard panels. They provide a lightweight alternative to using a full Universe / ActionBox when the goal is primarily to render, stream, or control visual content in the GUI workspace.

In practical terms, a Frame is usually a self-contained web application under FRAMEs/ that exposes an HTTP UI and control API. The Wolf GUI can open the Frame URL in a dashboard panel, while agents or scripts can update the Frame by calling its backend endpoints.

Frames are useful when you want to display or control content such as:

images, overlays, plots, and screenshots;
Markdown notes rendered as HTML;
audio, video, PDFs, text, and tables;
lightweight custom visualizations;
task-specific status pages or dashboards.

Frames complement, but do not replace, Universes / ActionBoxes:

Capability	Frame	Universe / ActionBox
Primary role	Display or webapp surface for GUI dashboard panels	Sandboxed environment hosting KBs, TBs, tools, APIs, and actions
Typical scope	Lightweight local backend/web UI	Rich executable environment with discovery and remote interaction
Best for	Rendering content, dashboards, visual context, panel apps	Tool execution, isolated runtimes, remote/local sandboxes, KB/TB hosting
GUI usage	Open the Frame URL directly in a dashboard panel	Register/open a Universe app or interact through Universe actions

Default media dashboard Frame

The repository includes a reusable media dashboard template at:

FRAMEs/dashboards/view_files/

It is a FastAPI app that can display images, Markdown, audio, video, PDFs, CSV/TSV tables, text, and other browser-supported media. It also includes a small controller script for updating the dashboard payload and display settings:

FRAMEs/dashboards/view_files/update_dash.py

Example update commands after the Frame is running:

FRAMEs/dashboards/view_files/update_dash.py --host 127.0.0.1 --port 8012 --payload /path/to/overlay.png
FRAMEs/dashboards/view_files/update_dash.py --host 127.0.0.1 --port 8012 --payload /path/to/notes.md --mime-type text/markdown
FRAMEs/dashboards/view_files/update_dash.py --host 127.0.0.1 --port 8012 --background black --zoom 1.25
FRAMEs/dashboards/view_files/update_dash.py --host 127.0.0.1 --port 8012 --control loop

Running Frames with `./wolf frame`

The root ./wolf command includes a frame command group, with frames as an alias:

./wolf frame --help
./wolf frames --help

Run the default dashboard Frame inline:

./wolf frame run --host 127.0.0.1 --port 8012

Run a specific Frame inline:

./wolf frame run ./FRAMEs/dashboards/view_files --host 127.0.0.1 --port 8012

The default runner uses the project uv environment:

uv run uvicorn main:app --app-dir <APP_DIR> --host <HOST> --port <PORT>

Alternative runner modes are available:

./wolf frame run --runner uv --host 127.0.0.1 --port 8012       # default
./wolf frame run --runner python --host 127.0.0.1 --port 8012
./wolf frame run --runner uvicorn --host 127.0.0.1 --port 8012

Deploying Frame replicas

wolf frame deploy can copy a Frame template and then launch the copied app. This is useful when several GUI dashboard panels need independent backend state.

Run an existing Frame inline:

./wolf frame deploy ./FRAMEs/dashboards/view_files --host 127.0.0.1 --port 8012

Copy the default dashboard template and run the copy inline:

./wolf frame deploy ./FRAMEs/dashboards/view_files \
  --copy ./FRAMEs/dashboards/dashboard2 \
  --host 127.0.0.1 --port 8013

If --sname is provided, the Frame launches in a detached GNU screen session:

./wolf frame deploy ./FRAMEs/dashboards/view_files \
  --copy ./FRAMEs/dashboards/dashboard2 \
  --host 127.0.0.1 --port 8013 \
  --sname dash2

If --sname is omitted, deploy runs inline and blocks the terminal, just like wolf frame run.

Useful screen commands for detached Frame deployments:

screen -ls
screen -r dash2
screen -S dash2 -X quit

Useful deploy options:

--force-copy    # replace an existing copy destination
--replace       # replace an existing screen session with the same --sname
--reload        # pass --reload to uvicorn

Implementation files:

framework/utils/frame_dashboard.py          # shared run/deploy implementation
framework/cli/wolf_app.py                   # registers wolf frame / wolf frames
FRAMEs/dashboards/view_files/main.py        # default media dashboard backend
FRAMEs/dashboards/view_files/update_dash.py # default media dashboard controller

Architecture Overview

Startup path

The current interactive startup path is:

./wolf
  -> python -m framework.cli.wolf_app
  -> framework/cli launchers
  -> framework/utils/config_tools.py
  -> CliSession.create_session(...)
  -> setup_cli_session(...)
  -> FastTurnBasedWorkflow.run(...)

The traditional runner follows a similar path:

runners/interactive.py
  -> load default session params
  -> load default LLM config
  -> CliSession(...)
  -> create_session(...)
  -> session['wf'].run(user_name='user')

The websocket gateway path is now:

framework/pack/gateway.py
  -> authenticate/connect websocket session
  -> create runtime bundle once per session
  -> setup_cli_session(..., workflow_cls=GatewayActionWorkflow)
  -> on chat: acquire session asyncio.Lock
  -> GatewayActionWorkflow.process_user_message(...)
  -> emit workflow_status/workflow_action/workflow_result/workflow_error events

Session construction

Session construction is handled primarily by:

framework/utils/config_tools.py

A new CLI session typically creates:

Main agent and optional worker agents.
Configured universes/actionboxes.
Chroma-backed vector stores for summaries and traces.
BaseChatManager.
MemoryManager.
ContextManager.
BaseInfrastructure.
Active workflow, usually FastTurnBasedWorkflow.

A session dictionary contains roughly:

{
    "agents": {
        "main": main_agent,
        "workers": workers,
    },
    "objects": {
        "universes": universes,
        "kbs": knowledgebases,
        "tbs": toolboxes,
    },
    "managers": {
        "chat": chat_manager,
        "memory": memory_manager,
        "context": context_manager,
    },
    "session_dir": session_dir,
    "db_client": db_client,
    "wf": workflow,
}

Active workflow

The active interactive workflow is:

framework/workflows/custom_workflows/turn_based_workflow.py

It provides the main turn-based loop. On each agent turn, the workflow:

Shows updated history.
Gets compacted context from the context manager.
Builds a prompt containing role instructions, context, workflow rules, behavior guidance, infrastructure description, and the allowed action schema.
Calls the selected agent.
Validates the response as a JSON action.
Appends the action to history.
Executes the action through the infrastructure layer.
Routes the next turn using yield_motion_to, receiver, or a system fallback.

Structured Actions

Agents do not respond with arbitrary free text. They respond with JSON actions.

In WOLF, an action is not just a tool call. It is a structured expression of intent. The payload says what parameters to use; the purpose says why the agent chose the action; the expectations say what result would count as success; the routing fields say who should act next. This makes actions useful both for execution and for later evaluation.

Action models live under:

framework/workflows/agent_actions/

Actions are dynamically discovered by:

framework/workflows/workflow_models.py

The framework imports action modules, walks subclasses of AgentAction, and builds a discriminated Pydantic union. This union becomes the schema shown to agents at runtime. The selected action set is the agent's current action space.

A curated action space is a policy surface. By changing which actions are available, how they are described, and what expectations are attached to them, WOLF can shape how agents explore, exploit, delegate, inspect, remember, and recover from failure.

Common action areas include:

Messaging actions, such as send_message.
File IO actions, such as read_file and write_file.
System actions, such as run_syscall.
GUI/VUI actions, such as dashboard publishing, visual context inspection, and permissioned capture.
Memory and context actions.
Universe discovery and health actions.
Knowledgebase actions.
Toolbox actions.
Deployment actions.
Playbook/workplan actions.

Because action traces include intent and expectation metadata, they can be scored after the fact. This enables reward-driven improvement of strategies, methods, and policies without requiring every improvement to be hard-coded into the model weights.

Adding a new action

To add a new workflow action:

Add or edit a module in:
```
framework/workflows/agent_actions/
```
Define a class inheriting from AgentAction.
Give it a unique action discriminator.
Define a Pydantic payload model if needed.
Override execute(self, infra) if it has side effects.
Restart the application so dynamic discovery rebuilds the action union and schema.

Important schema detail: write_file expects file_path, not filename.

Infrastructure Layer

The infrastructure layer is the local runtime interface used by workflows and actions.

Primary file:

framework/infrastructure/base_infrastructure.py

BaseInfrastructure owns or coordinates:

Main agent.
Worker agents.
Runtime objects such as universes, KBs, and TBs.
Chat history.
Full structured context.
Console/log display state.
Memory manager.
Context manager.
Chat manager.
Local command parsing.
Multimodal user input preparation.

The default infrastructure description is loaded from:

framework/infrastructure/config/base_infra_description.md

Memory and Context Management

The current memory/context system separates durable history from active LLM context.

Design principles:

Full chat/session history is durable and authoritative.
Active context is a curated working view.
Context compression removes information from active context, not from durable history.
Deletion and forgetting should be explicit and confirmation-gated where actions expose it.

Important files:

framework/infrastructure/base_memory_manager.py
framework/infrastructure/base_context_manager.py
framework/workflows/agent_actions/ctx_mem_management_actions.py
framework/workflows/agent_actions/ctx_window_advanced_actions.py

The context manager supports:

Context utilization diagnostics.
Automatic rebuild thresholds.
Context manifest / ledger generation.
Pinned context entries.
Working-memory packets.
Context policy metadata.
Snapshot and restore.

The working-memory packet may track:

Current objective.
Current plan.
Current step.
Active files.
Modified files.
Open tasks and questions.
Decisions.
Known bugs or warnings.
Last successful action.
Next recommended action.

Universes / ActionBoxes

Universes, also called ActionBoxes, are sandbox environments connected to the system. They can host knowledgebases, toolboxes, and executable actions. They may be local, remote, containerized, or otherwise isolated.

Universes are central to the WOLF learning-frame view: they are environments where agents can discover capabilities, test methods, gather observations, and learn locality-aware policies. A tool call is an isolated operation; a universe is an explorable world with its own state, affordances, constraints, KBs, TBs, and possible rewards.

Relevant files include:

framework/universes/base_universe.py
framework/universes/data_models.py
framework/universes/universe_tools.py
framework/universes/run_universe.py
framework/universes/remote_deployment.py

A typical universe configuration shape is:

{
    "host": "0.0.0.0",
    "port": 8115,
    "scheme": "http",
}

The framework can discover known universes, inspect universe health, list tools, and interact with KBs/TBs hosted inside a universe.

Knowledgebases, Toolboxes, and Vector Stores

The infrastructure stack is compositional:

VectorStore
  -> KnowledgeBase
  -> Tool
  -> ToolBox
  -> Universe / ActionBox

VectorStore

framework/data_store/vstore.py

Chroma-backed vector storage for embeddings, retrieval, and ingestion.

KnowledgeBase

framework/knowledgebase/knowledge_base.py
framework/knowledgebase/base_multimodal_knowledgebase.py
framework/knowledgebase/data_models.py

Knowledgebases combine vector storage with document inventory and metadata.

Tool and ToolBox

framework/tooling/tools.py
framework/tooling/toolbox.py
framework/tooling/tool_models.py

A Tool describes and executes a language-agnostic tool. A ToolBox manages multiple tools, supports discovery, documentation search, and execution.

Sessions, Persistence, and Resume

New sessions are created under:

wf_workspace/session_YYYYMMDD_HHMMSS

Workflow snapshots are saved to:

wf_workspace/session_YYYYMMDD_HHMMSS/session.snapshot.json

The workflow saves state after history updates. Snapshots include infrastructure state, workflow state, manager state, context, memory, roles, and session metadata.

Resume identifiers may include:

last
latest
recent
session_YYYYMMDD_HHMMSS
wf_workspace/session_YYYYMMDD_HHMMSS
/path/to/session.snapshot.json

Example:

./wolf cli --resume last

You can inspect sessions with:

./wolf sessions list
./wolf sessions inspect last

Configuration

Default session inputs live in:

config/session/default/params/inputs.py

Current active defaults include:

tiktoken_cache_dir
banner_image_file
banner_image_color
banner_image_width
universes
kbs
tbs
verbose

Default inference settings live in:

config/defaults/inference_engine.py

The root CLI supports config inspection and validation:

./wolf config print --config sessions/example_cli_session.json
./wolf config validate --config sessions/example_cli_session.json

Prompt, Rules, and Behavior Files

The base workflow loads user-editable preference files from:

config/preferences/rules/workflow/basewf.md
config/preferences/behaviour/workflow/basewf.md
config/preferences/prompts/workflow/basewf_default_assistant_sys_prompt.md

The infrastructure description is loaded from:

framework/infrastructure/config/base_infra_description.md

These files are embedded into the runtime prompt sent to agents.

Developer Notes

Important implementation files

Area	File
CLI app entrypoint	`framework/cli/wolf_app.py`
CLI config loading	`framework/cli/config_loader.py`
CLI launch dispatch	`framework/cli/launchers.py`
Workflow discovery	`framework/cli/discovery.py`
Session commands	`framework/cli/session_commands.py`
Session construction	`framework/utils/config_tools.py`
Base workflow	`framework/workflows/base_workflow.py`
Active CLI workflow	`framework/workflows/custom_workflows/turn_based_workflow.py`
Gateway workflow	`framework/workflows/custom_workflows/gateway_action_workflow.py`
Action discovery	`framework/workflows/workflow_models.py`
Action base class	`framework/workflows/base_agent_action.py`
Infrastructure	`framework/infrastructure/base_infrastructure.py`
Chat manager	`framework/infrastructure/base_chat_manager.py`
Memory manager	`framework/infrastructure/base_memory_manager.py`
Context manager	`framework/infrastructure/base_context_manager.py`

Current known cleanup / investigation areas

The living architecture notes identify several areas worth reviewing as the codebase evolves:

framework/workflows/workflow_models.py:get_actions_subset() may need correction for subset union construction.
Resume/session loading exists in more than one place and may need consolidation.
framework/orchestration/ appears adjacent to, or an evolution of, the workflow system and needs deeper tracing.
Older launchers remain in runners/ and may be historical, experimental, or compatibility paths.

Living Documentation

This repository includes living documentation intended for future humans, agents, and public contributors:

philo.md
app.md
wisdom.md
wisdom_nuggets/

philo.md is the public WOLF philosophy and invitation to contribute ideas, critiques, failure modes, capability levels, safety concerns, and standardization proposals.
app.md is the broad architectural overview and current working model.
wisdom.md is the registry of focused source-grounded discoveries.
wisdom_nuggets/*.nug files contain narrower, reusable pieces of development knowledge.

When adding a new nugget:

Place it under wisdom_nuggets/ unless another location is clearly better.
Include YAML front matter.
List source files inspected.
Add a registry entry to wisdom.md.
Cross-reference it from app.md if it changes the high-level model.

License

Notice of Copyright Assertion (O5088).

Triad National Security, LLC. All rights reserved. This program was produced under U.S. Government contract 89233218CNA000001 for Los Alamos National Laboratory (LANL), which is operated by Triad National Security, LLC for the U.S. Department of Energy/National Nuclear Security Administration. All rights in the program are reserved by Triad National Security, LLC, and the U.S. Department of Energy/National Nuclear Security Administration. The Government is granted for itself and others acting on its behalf a nonexclusive, paid-up, irrevocable worldwide license in this material to reproduce, prepare derivative works, distribute copies to the public, perform publicly and display publicly, and to permit others to do so.

Modified BSD 3-Clause License

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
Redistributions or derivative works must give appropriate credit to the original authors, including citation of the original publication or repository.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT INCLUDING NEGLIGENCE OR OTHERWISE ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Name		Name	Last commit message	Last commit date
FRAMEs/dashboards/view_files		FRAMEs/dashboards/view_files
config		config
framework		framework
public		public
runners		runners
sessions		sessions
tests		tests
wisdom_nuggets		wisdom_nuggets
.gitignore		.gitignore
.python-version		.python-version
LICENSE		LICENSE
README.md		README.md
app.md		app.md
environment.yml		environment.yml
install_dependencies.sh		install_dependencies.sh
nuke_pycaches.sh		nuke_pycaches.sh
philo.md		philo.md
pyproject.toml		pyproject.toml
road_plan.md		road_plan.md
sample.env		sample.env
sample_llm_config.json		sample_llm_config.json
wisdom.md		wisdom.md
wolf		wolf

Uh oh!

Latest commit

History

Folders and files

Repository files navigation