Metadata-Version: 2.4
Name: fieldstate-agent
Version: 0.1.0
Summary: 80% fewer tokens for multi-step AI agents. Same quality.
Author: Mithilesh
License: MIT
Project-URL: Homepage, https://web-production-44f2d7.up.railway.app
Project-URL: Demo, https://web-production-44f2d7.up.railway.app
Project-URL: Repository, https://github.com/yourusername/fieldstate
Keywords: ai,agents,llm,anthropic,token-reduction,memory,fieldstate
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: anthropic>=0.25.0
Requires-Dist: numpy>=1.24
Requires-Dist: sentence-transformers>=2.2
Requires-Dist: python-dotenv>=1.0
Provides-Extra: web
Requires-Dist: fastapi>=0.110; extra == "web"
Requires-Dist: uvicorn>=0.27; extra == "web"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# FieldState

**80% fewer tokens for multi-step AI agents. Same quality.**

[![PyPI](https://img.shields.io/pypi/v/fieldstate-agent?color=22c55e)](https://pypi.org/project/fieldstate-agent)
[![Python](https://img.shields.io/badge/python-3.11+-blue)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Demo](https://img.shields.io/badge/live-demo-orange)](https://web-production-44f2d7.up.railway.app)

Standard agents re-read their full conversation history every step — cost grows linearly, forever. **FieldState** replaces history with a compact geometric field state: flat cost per step, regardless of task length. Plus real-time signals when your agent drifts, conflicts, or suppresses an objective.

**[Try the live demo →](https://web-production-44f2d7.up.railway.app)**

---

## Benchmark results

Measured on `claude-haiku-4-5-20251001` via `response.usage`. Two independent runs.

| Steps | Standard agent | FieldState | Saving |
|-------|---------------|------------|--------|
| 6     | 11,540 tokens  | 3,408      | **70%** |
| 12    | 42,487 tokens  | 6,821      | **84%** |
| 20    | ~111,000       | ~11,000    | **90%** |
| 50    | ~670,000       | ~28,000    | **96%** |

Quality: **5/5** on both agents (LLM-as-judge, thoroughness + clarity).

```
Input tokens per step — Standard (↑) vs FieldState (—)

6000 │                                      ╱
     │                                    ╱
4000 │                                  ╱
     │                               ╱
2000 │                           ╱
     │     ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁
   0 └──────────────────────────────────
     Step  1   2   3   4   5   6  ...  12
```

---

## Install

```bash
pip install fieldstate-agent
```

---

## Usage

### Option 1 — FieldAgent (drop-in for any task)

```python
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
)

# Each step: returns output + a field signal
output, signal = agent.step("What are the security issues in auth.py?")
print(output)

# Field signals — things standard agents never see
if signal.suppressed:
    print(f"⚠ {signal.suppressed} is being ignored — agent losing balance")

if signal.conflict:
    print(f"⚡ Objectives in conflict: {signal.basins}")

if signal.drift:
    print(f"↘ Drifting toward {signal.drift_toward}")

# Token tracking
print(f"Saving so far: {agent.token_savings_pct:.0f}%")
print(agent.summary())
```

### Option 2 — Drop-in replacement for existing Anthropic code

Change one line. Everything else stays identical.

```python
# 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 description",
    objectives=["accuracy", "speed", "clarity"]
)

# Identical API — no other changes needed
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"Token saving: {client.token_savings_pct:.0f}%")
print(f"Last signal: {client.last_signal}")
```

### Option 3 — Compare both agents on any task

```python
from fieldstate import compare

results = compare(
    task="Plan a product launch strategy",
    objectives=["user_value", "feasibility", "revenue_impact"],
    steps=[
        "What are the top 3 pain points we should address?",
        "Which single feature should we build first?",
        "The CEO says revenue matters more than growth. Does that change things?",
        "A competitor launched last week. How should we respond?",
        "Summarize the roadmap in 3 bullet points.",
    ]
)

print(f"Token saving: {results['token_saving_pct']}%")
print(f"Signals fired: {results['signals_fired']}")
```

### Option 4 — Web UI (run locally)

```bash
pip install "fieldstate-agent[web]"
fieldstate serve
# Open http://localhost:8000
```

---

## Field signals

FieldState tracks your agent's objectives geometrically. After each step it detects:

| Signal | What it means | What to do |
|--------|--------------|------------|
| `conflict` | Objectives pulling in different directions | Surface the trade-off explicitly |
| `suppressed` | One objective being systematically ignored | Correct at the next step |
| `drift` | Agent losing balance toward one objective | Recalibrate |
| `deadlock` | Genuine impasse, no objective resolving | Escalate to human |

Standard agents have no awareness of any of these. FieldState surfaces them in real time.

---

## How it works

Instead of re-reading conversation history, FieldState maintains a 64-dimensional field state per objective. After each step, a local field engine updates the state — **zero API cost**. Before each step, ~30 tokens of field state replace thousands of tokens of history.

```
Standard agent:
  Step N: [system 450 tokens] + [full history grows forever] + [task]

FieldState:
  Step N: [last exchange ~200 tokens] + [field state ~30 tokens] + [task]
  ─────────────────────────────────────────────────────────────────────
  Cost stays flat. History is compressed into geometry, not prose.
```

---

## When it helps most

✅ Tasks with **6+ steps** — savings compound with each step  
✅ **Multi-objective tasks** — conflict/suppression detection adds value  
✅ **Long-running autonomous agents** — 90%+ saving at 20+ steps  
✅ **Goal shifts mid-task** — field detects and surfaces them  

❌ Tasks of **1–3 steps** — overhead exceeds savings at very short tasks  
❌ Tasks needing **verbatim recall of early messages** — use with fact register  

---

## Requirements

- Python 3.11+
- Anthropic API key (`sk-ant-...`)
- Works with any Anthropic model (Haiku recommended for cost efficiency)

---

## License

MIT — use it, fork it, build on it.

---

## Links

- **Live demo:** https://web-production-44f2d7.up.railway.app
- **Benchmark code:** `fieldstate/agents/token_benchmark_v3.py`
- **Paper (coming soon):** arXiv preprint in preparation
