Kit Reference

qitos.kit provides concrete, reusable building blocks for common agent authoring patterns. All components attach to the AgentModule + Engine pipeline and do not introduce a second orchestrator. Key terms used on this page:

parser: a component that converts raw model output into a typed Decision
protocol: the output format the model is asked to follow
transport: the adapter that sends requests to and receives responses from a model API
harness: the wiring layer that connects a transport, parser, and protocol into a coherent model-facing configuration
preset: a reusable configuration bundle for a model family
critic: a module that evaluates each step and can trigger retries or stops
trace: a structured log of all run events and steps

from qitos.kit import ReActTextParser, WindowMemory, CodingToolSet, ...

How to read this page

Use this page as a capability map for QitOS authoring.

If you are deciding…	Start here
How the model should emit actions	Parsers
How to keep useful context in long runs	Memory and history/compaction
Which tools to expose	Tool sets
Which ready-made registries to start from	Preset builders
How to add planning or search structure	Planning
How to start screenshot-first multimodal work	`ScreenshotEnv` and the visual guide
How to build desktop / computer-use agents	`DesktopEnv`, `ComputerUseToolSet`, and the desktop guide

Capability map

Parsers

ReActTextParser for Thought: / Action: protocols
JsonDecisionParser for JSON decision objects
XmlDecisionParser for XML protocols
MiniMaxToolCallParser when the model returns function-call-like structures
TerminusJsonParser and TerminusXmlParser for explicit termination-aware formats

Tool presets

coding_tools(...) for the canonical coding workspace
computer_use_tools() for provider-neutral desktop / GUI action workflows
advanced_coding_tools(...) for a Claude-style coding preset
web_tools() for web research and extraction
task_tools(...) for persistent task-board workflows
security_audit_tools(...) for defensive repository review
thinking_tools() for explicit thought-recording flows
notebook_tools(...), report_tools(...), and epub_tools(...) for narrower scenarios

Environments

ScreenshotEnv for screenshot-first multimodal and GUI-adjacent workflows
DesktopEnv for OSWorld-inspired desktop and computer-use loops
TextWebEnv for text-browser-style web observation
TmuxEnv for interactive terminal workflows

ScreenshotEnv is the first built-in multimodal environment. Use it when you want to test screenshot-based reasoning, visual-web prompting, or the new qita visual-asset path without committing to a full benchmark adapter. DesktopEnv builds on the same multimodal core but adds an OSWorld-style desktop lane: screenshot + accessibility + terminal observation, GUI controller ops, and container-first provider boundaries.

Long-running context blocks

WindowHistory for simple recency windows
TokenBudgetSummaryHistory for token-budget summarization
CompactHistory for multi-stage compaction with warning and summary events
WindowMemory, SummaryMemory, VectorMemory, and MarkdownFileMemory for cross-step recall

Planning and search

NumberedPlanBuilder for explicit plans
PlanCursor for plan execution bookkeeping
DynamicTreeSearch for branch selection and search-driven agents

Parsers convert raw LLM output strings into typed Decision objects. Choose the parser that matches the output format your prompt requests.

Prompt format and parser must match exactly. If your prompt asks for Thought: / Action: blocks, use ReActTextParser. If it asks for JSON, use JsonDecisionParser. If it asks for XML, use XmlDecisionParser.

ReActTextParser

Parses ReAct-style text output with labeled blocks such as Thought: and Action:.

from qitos.kit import ReActTextParser

class ReActTextParser(BaseParser[dict[str, Any]])

Constructor

def __init__(
    self,
    *,
    thought_keys: Optional[Sequence[str]] = None,
    reflection_keys: Optional[Sequence[str]] = None,
    action_keys: Optional[Sequence[str]] = None,
    final_keys: Optional[Sequence[str]] = None,
)

Parameter	Default recognized keys	Description
`thought_keys`	`thought, thinking, think, rationale`	Keys for the reasoning block
`reflection_keys`	`reflection, reflect, selfreflection`	Keys for self-reflection blocks
`action_keys`	`action, tool, call`	Keys for the action block
`final_keys`	`finalanswer, final, answer`	Keys for the final answer block

Usage

from qitos.kit import ReActTextParser

parser = ReActTextParser()

# Expects output like:
# Thought: I should search for the answer.
# Action: search(query="QitOS architecture")

Pass parser to AgentModule.run() or the Engine constructor.

JsonDecisionParser

Parses JSON-formatted model output. Supports mode field ("act", "final", "wait") and configurable key names.

from qitos.kit import JsonDecisionParser

class JsonDecisionParser(BaseParser[dict[str, Any]])

Constructor

def __init__(
    self,
    *,
    thought_keys: Optional[Sequence[str]] = None,
    reflection_keys: Optional[Sequence[str]] = None,
    action_keys: Optional[Sequence[str]] = None,
    final_keys: Optional[Sequence[str]] = None,
)

Same parameter names as ReActTextParser. All keys default to the same values.Usage

from qitos.kit import JsonDecisionParser

parser = JsonDecisionParser()

# Expects output like:
# {"thought": "I need to search.", "action": {"name": "search", "args": {"query": "..."}}}

XmlDecisionParser

Parses XML-formatted model output. Supports both XML mode attribute and configurable tag names.

from qitos.kit import XmlDecisionParser

class XmlDecisionParser(BaseParser[dict[str, Any]])

Constructor

def __init__(
    self,
    *,
    thought_keys: Optional[Sequence[str]] = None,
    reflection_keys: Optional[Sequence[str]] = None,
    action_keys: Optional[Sequence[str]] = None,
    final_keys: Optional[Sequence[str]] = None,
    xml_think_tags: Optional[Sequence[str]] = None,
    xml_reflection_tags: Optional[Sequence[str]] = None,
    xml_action_tags: Optional[Sequence[str]] = None,
    xml_final_tags: Optional[Sequence[str]] = None,
)

xml_*_tags take priority over *_keys for XML parsing. Defaults: xml_think_tags=("think", "thought", "thinking", "rationale"), xml_action_tags=("action", "tool", "call"), xml_final_tags=("final_answer", "final", "answer").Usage

from qitos.kit import XmlDecisionParser

parser = XmlDecisionParser()

# Expects output like:
# <response mode="act">
#   <think>I should search.</think>
#   <action name="search"><query>QitOS docs</query></action>
# </response>

TerminusJsonParser / TerminusXmlParser

Terminus parsers are specialized variants that handle agent formats with explicit <terminus> or JSON-level termination signals. Use them with their matching system prompts (TERMINUS_JSON_SYSTEM_PROMPT, TERMINUS_XML_SYSTEM_PROMPT).

from qitos.kit import TerminusJsonParser, TerminusXmlParser

Both share the same constructor signature as JsonDecisionParser and XmlDecisionParser respectively.

Long-running context management in QitOS is a first-class authoring concern.The key separation is:

History controls what goes back into the next model call
Memory stores useful records outside the immediate chat window

WindowHistory

WindowHistory is the simplest history strategy. It keeps a fixed sliding message window.Use it when:

your runs are short
you want deterministic recency behavior
you do not want summaries or compaction

TokenBudgetSummaryHistory

TokenBudgetSummaryHistory watches a token budget and summarizes older messages into one continuation message when needed.Use it when:

your runs are getting longer
you want a cheap “summary instead of overflow” behavior
you do not need the richer compaction controls of CompactHistory

CompactHistory

CompactHistory is the most advanced built-in context compactor.It supports:

warning thresholds before overflow
round grouping with MessageGrouper
micro-compaction of large old messages
summary compaction for earlier rounds
runtime metadata and compaction events that can surface in traces

Use it when:

you are building long-running agents
you want compaction to be inspectable
you want more control than a simple summary fallback

CompactConfig

CompactConfig controls the compaction behavior, including:

max_tokens
keep_last_rounds
keep_last_messages
warning_ratio
auto_compact
micro-compaction preview sizes
summary length limits

MessageGrouper

MessageGrouper groups messages into compactable rounds. It prefers grouping by step when possible, and falls back to assistant-boundary grouping otherwise.This matters because QitOS compacts context in ways that preserve the structure of an agent trajectory (the sequence of observations and decisions across steps).

Memory adapters implement qitos.Memory and give your agent persistent recall across steps.

WindowMemory

Keeps the last N records in memory. Oldest records are dropped when the window overflows.

from qitos.kit import WindowMemory

Constructor

def __init__(self, window_size: int = 20)

Parameter	Default	Description
`window_size`	`20`	Maximum number of records to retain in memory

Usage

from qitos.kit import WindowMemory

memory = WindowMemory(window_size=30)
agent = MyAgent(memory=memory, ...)

SummaryMemory

Keeps the last N records in memory and compresses older records into a summary string when evict() is called.

from qitos.kit.memory import SummaryMemory

Constructor

def __init__(self, keep_last: int = 10)

Parameter	Default	Description
`keep_last`	`10`	Number of recent records to keep verbatim

When evict() runs, records beyond keep_last are pipe-joined into self._summaries for later retrieval via summarize().

MarkdownFileMemory

Persists all memory records to a local markdown file in an append-only format. Useful for debugging and long-running agents that need durable memory.

from qitos.kit import MarkdownFileMemory

Constructor

def __init__(self, path: str = "memory.md", max_in_memory: int = 200)

Parameter	Default	Description
`path`	`"memory.md"`	Path to the markdown file (created if absent)
`max_in_memory`	`200`	Maximum records held in memory; older records are dropped from RAM but remain on disk

Each appended record is written as a markdown section:

## Step 3 · observation
- time_utc: 2026-04-07T10:00:00+00:00

```text
{"result": "..."}

</Accordion>

<Accordion title="VectorMemory">

Stores records in an in-process embedding index and retrieves the top-K most similar records for a given query.

```python
from qitos.kit.memory import VectorMemory

Constructor

def __init__(self, top_k: int = 5)

Parameter	Default	Description
`top_k`	`5`	Number of most-relevant records to return

Factory helpers

from qitos.kit.memory import window_memory, summary_memory, vector_memory, markdown_file_memory

memory = window_memory(window_size=20)
memory = summary_memory(keep_last=10)
memory = vector_memory(top_k=5)
memory = markdown_file_memory(path="memory.md", max_in_memory=200)

Tool sets bundle related tools with shared lifecycle hooks (setup / teardown). Register them with ToolRegistry.register_toolset().

CodingToolSet

Full coding bundle combining editor, codebase search, file I/O, shell, and optionally notebook tools.

from qitos.kit import CodingToolSet

Constructor

def __init__(
    self,
    workspace_root: str = ".",
    shell_timeout: int = 30,
    include_notebook: bool = True,
    enable_lsp: bool = True,
    enable_tasks: bool = True,
    enable_web: bool = True,
)

Typical usage

from qitos import ToolRegistry
from qitos.kit import CodingToolSet

registry = ToolRegistry()
registry.register_toolset(
    CodingToolSet(
        workspace_root="/path/to/project",
        include_notebook=False,
        enable_lsp=False,
        enable_tasks=False,
        enable_web=False,
        expose_modern_names=False,
    )
)

AdvancedCodingToolSet

Higher-level coding preset intended for Claude-style or operator-style long-running coding agents.

from qitos.kit.toolset import advanced_coding_tools

Use this preset when you want a richer coding workflow surface than the base coding_tools(...) bundle.

TaskToolSet

Persistent task-board tools backed by a JSON file. Useful for agents that manage multi-step plans.

from qitos.kit import TaskToolSet

Constructor

def __init__(
    self,
    workspace_root: str = ".",
    board_relpath: str = ".qitos/task_board.json",
)

ThinkingToolSet

Lightweight thought-recording tools for workflows that want explicit scratch thoughts as tool calls.

from qitos.kit.toolset import thinking_tools

registry = thinking_tools()

Use this as an opt-in research toolset rather than a default dependency for all agents.

ReportToolSet

Assessment and reporting tools for evaluation agents.

from qitos.kit import ReportToolSet

Constructor

def __init__(self, workspace_root: str = ".")

SecurityAuditToolSet

Defensive repository-audit tools for entrypoint discovery, sink analysis, secret scanning, dependency checks, and finding synthesis.

from qitos.kit import SecurityAuditToolSet

Typical usage

from qitos import ToolRegistry
from qitos.kit import SecurityAuditToolSet

registry = ToolRegistry()
registry.register_toolset(
    SecurityAuditToolSet(
        workspace_root="/path/to/repo",
        include_external=False,
        max_matches=80,
    )
)

Use this toolset when you want a defensive code-review or audit agent rather than a general editing agent.

NotebookToolSet

Jupyter notebook manipulation tools.

from qitos.kit.tool.notebook import NotebookToolSet

Constructor

def __init__(self, workspace_root: str = ".")

Tools provided: read_notebook, replace_notebook_cell, insert_notebook_cell.

WebToolSet

Web-oriented preset built around HTTP and extraction tools.

from qitos.kit.toolset import web_tools

registry = web_tools()

Use it for lightweight web research and scraping flows when you do not need the full coding preset.

Pre-built registry helpersThe qitos.kit.toolset module provides factory functions that return a configured ToolRegistry:

from qitos.kit.toolset import (
    advanced_coding_tools,
    codebase_tools,
    coding_tools,
    editor_tools,
    math_tools,
    notebook_tools,
    report_tools,
    task_tools,
    web_tools,
)

registry = coding_tools(workspace_root="/path/to/project", shell_timeout=60)
registry = advanced_coding_tools(workspace_root="/path/to/project")
registry = web_tools()

Stand-alone tool objects you can register directly.

HTTPGet / HTTPPost / HTTPRequest

HTTP request tools with automatic retries and structured response payloads.

from qitos.kit import HTTPGet, HTTPPost
from qitos.kit.tool.web import HTTPRequest

HTTPGet constructor

def __init__(
    self,
    headers: Optional[Dict[str, str]] = None,
    timeout: int = 30,
    max_retries: int = 2,
)

HTTPPost constructor — same signature as HTTPGet.HTTPRequest constructor

def __init__(
    self,
    headers: Optional[Dict[str, str]] = None,
    timeout: int = 30,
    max_retries: int = 2,
    backoff_factor: float = 0.4,
    user_agent: str = "QitOS-WebTool/1.0",
)

HTTPRequest.run() accepts method, url, params, data, json_data, headers, timeout, verify_tls, allow_redirects, max_content_chars.

HTMLExtractText

Extract readable text from raw HTML, optionally preserving anchor links.

from qitos.kit import HTMLExtractText

Constructor — HTMLExtractText() (no parameters)run(html, max_chars=6000, keep_links=False) — Returns {"status", "content", "length", "title"}.

SubmitAnswer

Utility tool used by benchmark-style agents to submit a final candidate answer or flag.

from qitos.kit.tool.cybench import SubmitAnswer

This is especially useful in CyBench-like settings where the agent must explicitly hand over a candidate result through a tool call rather than only return a final natural-language answer.

SendTerminalKeys

Send keystrokes to a terminal session (tmux or similar).

from qitos.kit import SendTerminalKeys

Useful for agents that need to interact with a long-running terminal process.

Planning helpers for building structured plans and search-driven agents.

NumberedPlanBuilder

Calls an LLM to generate a numbered plan from a prompt.

from qitos.kit import NumberedPlanBuilder

Constructor

def __init__(self, system_prompt: str = "Return a numbered plan only.")

build(llm, prompt, extra_messages=None) -> List[str]Calls llm with the system prompt and user prompt, then parses lines matching 1. ..., 2. ... etc. Returns the list of step strings.Usage

from qitos.kit import NumberedPlanBuilder

builder = NumberedPlanBuilder()
plan = builder.build(llm=agent.llm, prompt="How to analyse a Python codebase?")
# ["Read the directory structure", "Identify entry points", ...]

PlanCursor

Manages plan and cursor fields on a state object.

from qitos.kit.planning import PlanCursor

Constructor

def __init__(self, plan_field: str = "plan", cursor_field: str = "plan_cursor")

Methods

def init(self, state: Any, plan: List[str]) -> None
def current(self, state: Any) -> Optional[str]
def advance(self, state: Any) -> None
def done(self, state: Any) -> bool

DynamicTreeSearch

Adaptive tree search that maintains a frontier of unexplored candidates and selects branches by score plus novelty bonus.

from qitos.kit import DynamicTreeSearch

Constructor

def __init__(
    self,
    top_k: int = 3,
    max_frontier: int = 64,
    score_key: str = "score",
    exploration_bonus: float = 0.25,
)

Parameter	Default	Description
`top_k`	`3`	Candidates to keep per expansion
`max_frontier`	`64`	Maximum frontier size
`score_key`	`"score"`	Key in `Decision.meta` to read as base score
`exploration_bonus`	`0.25`	Bonus added for less-visited candidates

Pass it to Engine(search=DynamicTreeSearch(...)) or AgentModule.run(search=...).

State ops

Lightweight helpers for safely updating common state fields:

from qitos.kit.planning import append_log, format_action, set_final, set_if_empty

# Append a message to state.log (creates the list if absent)
append_log(state, "step completed")

# Render an action dict as a readable string
label = format_action({"name": "search", "args": {"query": "foo"}})

# Set state.final_result and stop_reason
set_final(state, result="Done", reason=StopReason.SUCCESS)

# Set a field only if it is currently falsy
set_if_empty(state, "plan", [])

Critics evaluate each step’s decision and action results, and can signal continue, retry, or stop to the Engine.

ReActSelfReflectionCritic

Generates reflection notes when tool calls fail and triggers retries up to a configurable limit.

from qitos.kit import ReActSelfReflectionCritic

Constructor

def __init__(self, max_retries: int = 2)

Parameter	Default	Description
`max_retries`	`2`	Maximum retry attempts before signalling `stop`

Behaviour

If any action result contains an "error" key: writes a structured reflection to state.metadata["self_reflections"] and returns action="retry".
After max_retries failed attempts: returns action="stop".
On a Decision.final() without errors: appends a pass note and returns action="continue".

Usage

from qitos.kit import ReActSelfReflectionCritic

critic = ReActSelfReflectionCritic(max_retries=3)
agent.run(task="...", critics=[critic])

SelfReflectionCritic

General-purpose self-reflection critic. Checks action results and produces structured feedback without the ReAct-specific format assumptions.

from qitos.kit.critic import SelfReflectionCritic

PassThroughCritic

A no-op critic that always returns action="continue". Useful as a placeholder during development.

from qitos.kit.critic import PassThroughCritic

The models module provides concrete LLM callables compatible with AgentModule.llm.For v0.4 research authoring, prefer the family-preset layer when you want one agent to switch across model families:

from qitos.harness import build_harness_policy, build_model_for_preset

Use OpenAICompatibleModel(...) directly when you are hand-authoring a single transport path.

OpenAICompatibleModel

Works with any OpenAI-compatible API endpoint — including SiliconFlow, Azure OpenAI, Tongyi, Zhipu AI, LM Studio, vLLM, and LocalAI.

from qitos.models import OpenAICompatibleModel

Constructor

def __init__(
    self,
    model: str = "default",
    api_key: Optional[str] = None,
    base_url: Optional[str] = None,
    system_prompt: Optional[str] = None,
    temperature: float = 0.7,
    max_tokens: int = 2048,
    timeout: int = 60,
)

Parameter	Default	Description
`model`	`"default"`	Model name sent to the API
`api_key`	`None`	Falls back to `OPENAI_API_KEY`; uses `"dummy-key"` if absent
`base_url`	`None`	Falls back to `OPENAI_BASE_URL`; required
`system_prompt`	`None`	Prepended as a system message to every call
`temperature`	`0.7`	Sampling temperature
`max_tokens`	`2048`	Maximum tokens in the response
`timeout`	`60`	Request timeout in seconds

Usage

from qitos.models import OpenAICompatibleModel

llm = OpenAICompatibleModel(
    model="Qwen/Qwen3-8B",
    base_url="https://api.siliconflow.cn/v1/",
    temperature=0.2,
)
agent = MyAgent(llm=llm, ...)

OpenAIModel

Direct OpenAI (GPT) model integration.

from qitos.models import OpenAIModel

Constructor

def __init__(
    self,
    model: str = "gpt-4",
    api_key: Optional[str] = None,
    base_url: Optional[str] = None,
    system_prompt: Optional[str] = None,
    temperature: float = 0.7,
    max_tokens: int = 2048,
    timeout: int = 60,
)

Reads OPENAI_API_KEY and OPENAI_BASE_URL from the environment by default.

Local models

from qitos.models import OllamaModel, LMStudioModel, VLLMModel

llm = OllamaModel(model="llama3")
llm = LMStudioModel(model="mistral", base_url="http://localhost:1234/v1")
llm = VLLMModel(model="meta-llama/Llama-3-8b", base_url="http://localhost:8000/v1")

All local models share the same base constructor signature as OpenAICompatibleModel.

ModelFactory

Automatically selects and constructs a model from environment variables.

from qitos.models import ModelFactory

llm = ModelFactory.from_env()

Reads QITOS_MODEL (or OPENAI_API_KEY / OPENAI_BASE_URL) to pick the right backend.Register a custom backend:

@ModelFactory.register("my_backend")
class MyModel(Model):
    ...

Documentation Index

​How to read this page

​Capability map

​Parsers

​Tool presets

​Environments

​Long-running context blocks

​Planning and search

​WindowHistory

​TokenBudgetSummaryHistory

​CompactHistory

​CompactConfig

​MessageGrouper

How to read this page

Capability map

Parsers

Tool presets

Environments

Long-running context blocks

Planning and search

WindowHistory

TokenBudgetSummaryHistory

CompactHistory

CompactConfig

MessageGrouper