InquiryCraft

InquiryCraft, shortened to iqcraft in project discussions and documentation, is a lightweight, extensible harness for building tool-using LLM agents. It provides the execution loop and lifecycle primitives needed by standalone agents, interactive CLIs, and larger host applications without imposing a domain workflow. The published package, Python import, and CLI command all remain inquirycraft; iqcraft is a short name, not a second compatibility entry point.

Release status

The current stable release is 0.8.1, published on PyPI. InquiryCraft is currently beta software and supports Python 3.11 and newer. Release tags use vMAJOR.MINOR.PATCH; the main branch may contain changes intended for the next release.

For a reproducible installation, pin the published version:

pip install 'inquirycraft==0.8.1'

Why InquiryCraft?

• Small core — the minimal installation depends only on Click.
• Real agent loop — provider request, tool call, tool result, and continuation are handled by a reusable AgentRuntime.
• Provider-neutral contracts — applications can implement LLMClient or use the optional OpenAI-compatible adapter.
• Composable tools — typed schemas, execution middleware, path policy, concurrent dispatch, output reduction, and raw artifact retention share one contract.
• Durable runs — append-only sessions, lifecycle events, cancellation, resume, and telemetry are built in.
• Deterministic validation — record/replay detects drift in messages, model options, tool schemas, call ordering, results, and stream mode.
• Optional integrations — provider SDKs, token counting, and MCP stay outside the minimal package.

Install

Install the minimal runtime and CLI:

pip install inquirycraft
inquirycraft tools list

Install an OpenAI-compatible provider client:

pip install 'inquirycraft[openai]'

Other optional extras:

pip install 'inquirycraft[tokens]'
pip install 'inquirycraft[mcp]'
pip install 'inquirycraft[tui]'

Importing inquirycraft resolves public symbols lazily. It does not initialize the CLI or load provider SDKs.

Quick start

Configure one or more OpenAI-compatible endpoints (comma-separated, in matching order):

export INQUIRYCRAFT_API_KEYS=key-a,key-b
export INQUIRYCRAFT_BASE_URLS=https://a.example/v1,https://b.example/v1
export INQUIRYCRAFT_MODELS=model-a,model-b

A single value is supported; one URL or model may be shared by all keys. Otherwise, URL and model counts must match the key count. Legacy Python factory calls that explicitly supply a scalar model retain their fallback and model-cycling behavior. CLI, REPL, and TUI use the same pool with retry, cooldown, and failover. Plural variables take precedence over legacy INQUIRYCRAFT_API_KEY, INQUIRYCRAFT_BASE_URL, and INQUIRYCRAFT_MODEL aliases. Copy env.example to .env if desired and load it with set -a; source .env; set +a in Bash; the standalone CLI does not automatically read .env.

The options are --models, --base-urls, and --api-keys-env; old singular option names remain aliases. --api-keys-env names an environment variable, not a key value.

Run a single task with the built-in file and shell tools:

mkdir -p workspace
inquirycraft run \
  --workspace ./workspace \
  "Inspect the workspace and write a concise summary to result.txt"

Start an interactive session:

inquirycraft repl --workspace ./workspace

Start the full-screen InquiryCraft TUI:

pip install 'inquirycraft[openai,tui]'
inquirycraft tui --workspace ./workspace

The TUI uses InquiryCraft's own IQ · InquiryCraft terminal wordmark and projects the same runtime event stream used by embedded hosts. It includes a scrollable transcript, streaming assistant and reasoning output, tool status cards, pending-message state, token/model/workspace footer data, and a multiline editor.

Submit with Enter (or Ctrl+S). Use Alt+Enter for a new line; Shift+Enter also works in terminals that distinguish it from Enter. While a run is busy, an ordinary submission is queued as steering instead of starting a concurrent run. Use /follow-up TEXT, /next TEXT, /cancel, /status, /clear, /help, or /quit; Ctrl+R toggles reasoning, Ctrl+O toggles tool details, and Ctrl+Q exits. The existing repl command remains available for plain terminals and scripts.

Applications embedding the InquiryCraft Click group can call create_cli(include_tui=False) when their dependency policy intentionally excludes Textual. The standalone inquirycraft command keeps TUI registration enabled by default.

Python API

import asyncio
import os
from pathlib import Path

from inquirycraft.adapters import AskLLMAdapter
from inquirycraft.llm import LLMFactoryConfig, build_llm
from inquirycraft.runtime import AgentRuntime, RuntimeOptions
from inquirycraft.tools import default_tools


async def main() -> None:
    models = os.environ["INQUIRYCRAFT_MODELS"].split(",")
    client = AskLLMAdapter(build_llm(LLMFactoryConfig(
        api_keys=os.environ["INQUIRYCRAFT_API_KEYS"].split(","),
        base_urls=os.environ["INQUIRYCRAFT_BASE_URLS"].split(","),
        models=models,
    )))
    runtime = AgentRuntime(
        llm=client,
        options=RuntimeOptions(
            model=models[0],
            workspace=Path("./workspace"),
            system_prompt="You are a careful coding agent.",
        ),
        tools=default_tools(),
    )
    try:
        print(await runtime.run("Inspect the workspace and summarize its contents."))
    finally:
        await client.aclose()


asyncio.run(main())

Implementing the LLMClient protocol is enough to connect another provider. Custom tools subclass BaseTool and return a ToolResult; hooks and event sinks can be added without modifying the loop.

Streaming, recovery, and runtime control

The compatibility run() -> str API and the event-stream API use the same agent loop. Enable provider streaming separately, and opt into the operation journal when a run must be recoverable across process restarts:

options = RuntimeOptions(
    model="your-model",
    workspace=Path("./workspace"),
    stream_llm=True,
    tool_execution="parallel",
    operation_log=Path(".inquirycraft/operations.jsonl"),
)
runtime = AgentRuntime(llm=client, options=options, tools=default_tools())

async for event in runtime.run_stream("Inspect the project"):
    print(event.type, event.payload)

Tool bundles are fully parsed and schema-validated before execution. Tools default to replay_policy = "never"; declare "safe" only when repeating an unsettled call is known to be safe. Runtime controls can be queued without starting a concurrent run:

await runtime.steer("Focus on the failing integration test")
await runtime.follow_up("Summarize the evidence")
await runtime.next_run("Use concise output on the next explicit run")

Hosted applications that execute their own domain policy loops can import process lifecycle helpers from inquirycraft.runtime and shell-output reducers from inquirycraft.tools. These package namespaces are the stable extension surface; hosts do not need to access the underlying runtime.subprocess or reducer modules. See the maintained Host Extension API for signatures, lifecycle ownership, platform constraints, safe cleanup patterns, and compatibility policy.

CompactionPolicy and injected context transformers change only the provider-visible projection. The append-only source conversation remains intact. When an operation log is configured, each conversation append also creates a durable projection; terminal records atomically carry the inactive state and final projection. On resume, settled LLM/tool deltas missing from the conversation store are reconstructed without repeating a completed provider request or a replay_policy="never" tool.

Context estimates prefer the latest provider-reported input usage and use the deterministic heuristic only for message deltas or as a fallback. Compacted requests persist a versioned, auditable checkpoint containing the source/provider views, summary boundary, retained tail, policy, token estimates, and optional provider usage.

Skills and prompt templates

ResourceLoader discovers declarative SKILL.md and *.prompt.md resources. Project roots require an explicit ResourceTrustStore decision by default. Discovery reads Markdown data only and never imports project Python. Skill catalogs expose only name and description; full instructions are read on demand.

Sessions, events, and replay

Persist a conversation and its lifecycle events:

inquirycraft run "continue the task" \
  --session-log .inquirycraft/session.jsonl \
  --event-log .inquirycraft/events.jsonl

Session logs are append-only. If the file already exists, run and repl restore its messages before the next turn.

RecordingLLMClient stores the exact provider-visible request and completion result or stream chunks. ReplayLLMClient consumes that JSONL offline and raises ReplayMismatchError when model parameters, messages, tool schemas, call ordering, or stream mode drift. Generated timestamps and event IDs can be normalized without loosening prompts, tool payloads, results, or ordering.

Tools and path policy

InquiryCraft includes independent read, write, edit, grep, glob, list, and shell tools. Filesystem scope is configured separately from tool behavior:

from inquirycraft.tools import PathPolicy, ReadTool

policy = PathPolicy("./workspace", enabled=True)
read = ReadTool(path_policy=policy)

A strict PathPolicy contains model-generated paths under a configured root and any explicitly allowed extra roots. Hosts that execute untrusted model output should also apply process isolation and least-privilege credentials appropriate to their threat model.

Tool-output bounds and raw artifacts

The Runtime applies one final output policy after tool hooks and before events, operation settlement, and Conversation persistence. Results up to 12,000 characters are unchanged. Larger results become an exact head/tail view; the complete rendered result is saved under .logs/tool_outputs/ with a SHA-256 fingerprint and an append-only index. Shell observation commands use the existing loss-preserving shell summary first.

from inquirycraft.tools import ToolOutputPolicy

runtime = AgentRuntime(
    ...,
    tool_output_policy=ToolOutputPolicy(max_model_chars=16_000),
)

# Explicit compatibility escape hatch; large output will remain model-visible.
unbounded = ToolOutputPolicy(enabled=False)

If raw artifact persistence fails, InquiryCraft returns the original unabridged result instead of silently discarding data. Error results remain errors after reduction.

CLI reference

inquirycraft run             Run one tool-using agent task
inquirycraft repl            Start an interactive multi-turn session
inquirycraft tui             Start the full-screen streaming terminal interface
inquirycraft tools list      List built-in tools
inquirycraft tools schema    Print tool schemas
inquirycraft events show     Inspect runtime event JSONL

Use inquirycraft COMMAND --help for command-specific options.

Package layout

See ARCHITECTURE.md for design boundaries and validation layers.

Development

uv sync --all-extras
uv run pytest -q
uv run ruff check .
uv run ruff format --check .
uv build

InquiryCraft supports Python 3.11 and newer and is distributed under the MIT License.

TUI assistant responses render Markdown by default (headings, lists, tables and syntax-highlighted fenced code). Use inquirycraft tui --no-markdown for literal text, or set INQUIRYCRAFT_TUI_MARKDOWN=false. --markdown explicitly enables it. Rendering applies to streamed and restored assistant messages; stored content remains the original Markdown. User input and tool output remain literal text.

Default CLI runtimes (run, REPL and TUI) enable deterministic context compaction with a default 128K window (131,072 tokens), an 8,192-token output reserve, a 2,048-token safety margin and an 80% input trigger. Original conversation records remain intact. This is not model context-window discovery or an LLM-generated semantic summary. Direct AgentRuntime embedding keeps its existing opt-in policy so host-owned context transformers are not compacted a second time.

In TUI, type / for command completion (Tab or Enter accepts, arrows select, Escape dismisses). /context configures 32K/64K/128K/256K/1M or a custom exact window (or enter /context 128K directly); output reserve, safety margin and trigger ratio are editable. /pricing sets optional USD-per-million input, cached-input and output prices; /usage shows session totals. The model footer displays estimated context occupancy, token-weighted cache hit rate and estimated cost, with details hidden on narrow terminals. The default capacity is 128K; unknown prices remain unset; no model capabilities or billing rates are inferred. These profiles affect interactive chat factories, not embedding applications' independent context policies.