FieldState

Installation

For the web UI (local comparison tool):

Requires Python 3.11+ and an Anthropic API key.

Quick Start

from fieldstate import FieldAgent

agent = FieldAgent(
    task="Review this codebase and suggest improvements",
    objectives=["thoroughness", "efficiency", "clarity"],
    api_key="sk-ant-..."  # or set ANTHROPIC_API_KEY
)

# Step 1
output, signal = agent.step("What are the security issues in auth.py?")
print(output)

# Step 2 — token cost stays flat, signal updates
output, signal = agent.step("How severe is the SQL injection risk?")

# Field signals — invisible to standard agents
if signal.suppressed:
    print(f"⚠ {signal.suppressed} is being suppressed")

print(f"Token saving: {agent.token_savings_pct:.0f}%")

FieldAgent

The main class. Wraps the Anthropic API with a field state engine. History is truncated to the last exchange; a compact field state replaces it.

from fieldstate import FieldAgent

agent = FieldAgent(
    task="Your task description",          # what the agent is doing
    objectives=["obj1", "obj2", "obj3"],  # 2–4 objectives
    api_key="sk-ant-...",                  # or ANTHROPIC_API_KEY env var
    model="claude-haiku-4-5-20251001",      # default
    max_tokens=600,                          # default
)

output, signal = agent.step("your message")

# Token tracking
agent.tokens_used          # total tokens used (input + output)
agent.input_tokens_used    # input tokens only
agent.token_savings_pct    # estimated % saved vs standard agent
agent.step_count           # number of steps run
agent.field_state          # current FieldSignal
agent.summary()            # formatted summary string

Drop-in Adapter

Already using the Anthropic SDK? Change one line.

# Before
import anthropic
client = anthropic.Anthropic(api_key="sk-ant-...")

# After — one line change
from fieldstate.adapters import FieldStateClient
client = FieldStateClient(
    api_key="sk-ant-...",
    task="Your agent's task",
    objectives=["accuracy", "speed", "clarity"],
)

# Identical API — no other changes
response = client.messages.create(
    model="claude-haiku-4-5-20251001",
    max_tokens=600,
    messages=[{"role": "user", "content": "Your message"}]
)

print(response.content[0].text)
print(f"Saving: {client.token_savings_pct:.0f}%")
print(f"Signal: {client.last_signal}")

Compare Helper

Run the same task through both agents and get a comparison dict.

from fieldstate import compare

results = compare(
    task="Plan a product launch",
    objectives=["user_value", "feasibility", "revenue"],
    steps=[
        "What are the top 3 pain points?",
        "Which feature should we build first?",
        "CEO says revenue matters more now. Does that change things?",
        "Summarize in 3 bullet points.",
    ],
    verbose=True  # prints live progress
)

print(results["token_saving_pct"])      # e.g. 67.3
print(results["signals_fired"])         # how many field signals
print(results["standard_input_tokens"])  # baseline
print(results["field_input_tokens"])     # FieldState

Web UI

Run a local comparison tool — type anything, both agents respond side by side.

# Install with web extras
pip install "fieldstate-agent[web]"

# Start the server
fieldstate serve

# Or from Python
from fieldstate.web.server import serve
serve(port=8000)

Or try the hosted demo →

Field Signals

After each step, FieldState returns a FieldSignal with real-time diagnostics about your agent's objective dynamics. Standard agents have no equivalent.

output, signal = agent.step("your message")

signal.conflict          # bool
signal.suppressed        # str | None — which objective
signal.drift             # bool
signal.drift_toward      # str | None — which objective is dominating
signal.deadlock          # bool
signal.basins            # dict — {objective: "decisive"|"synthesis"|"avoidance"|"collapse"}
signal.irrevs            # dict — {objective: 0.0–1.0 irreversibility}
signal.inertia           # float — overall field commitment (0–1)
signal.description       # str — plain English summary

How It Works

FieldState maintains one 64-dimensional state vector per objective (called a Mindlet). After each agent step:

Benchmarks

All measurements use claude-haiku-4-5-20251001, token counts from response.usage. Two independent runs confirmed.

Quality evaluation (LLM-as-judge, thoroughness + clarity): 5/5 on both agents across two task types.

API Reference

FieldAgent

FieldSignal properties

Limitations

Be aware of these before using in production:

• Short tasks (1–3 steps): Overhead exceeds savings. Break-even around step 4.
• Verbatim early recall: The fact register handles numbers and constraints. Free-form content from early steps may not be retained.
• Contradiction detection: Works when both conflicting instructions are extracted. Atypical phrasing may need additional patterns.
• Signal calibration: Signals are well-calibrated for planning and reasoning tasks. Domain-specific tasks may need objective tuning.