Metadata-Version: 2.4
Name: agentinputlab
Version: 0.1.0a2
Summary: Auditable, intent-aware input intervention for LLM agents
Author: Chuang Zhao, Xiaomeng Li
License-Expression: MIT
Project-URL: Homepage, https://github.com/Data-Designer/AgentInputLab
Project-URL: Repository, https://github.com/Data-Designer/AgentInputLab
Project-URL: Documentation, https://pypi.org/project/agentinputlab/
Keywords: agents,llm,prompt-optimization,retrieval,benchmark
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: THIRD_PARTY_NOTICES.md
Provides-Extra: smartsearch-prepare
Requires-Dist: requests<3,>=2.32; extra == "smartsearch-prepare"
Requires-Dist: tqdm<5,>=4.66; extra == "smartsearch-prepare"
Provides-Extra: smartsearch-sample
Requires-Dist: jieba==0.42.1; extra == "smartsearch-sample"
Requires-Dist: langid==1.1.6; extra == "smartsearch-sample"
Requires-Dist: numpy<2,>=1.26; extra == "smartsearch-sample"
Provides-Extra: smartsearch-policy
Requires-Dist: torch==2.6.0; extra == "smartsearch-policy"
Requires-Dist: torchvision==0.21.0; extra == "smartsearch-policy"
Requires-Dist: torchaudio==2.6.0; extra == "smartsearch-policy"
Requires-Dist: transformers==4.51.1; extra == "smartsearch-policy"
Requires-Dist: datasets==4.0.0; extra == "smartsearch-policy"
Requires-Dist: accelerate==1.9.0; extra == "smartsearch-policy"
Requires-Dist: peft==0.17.1; extra == "smartsearch-policy"
Requires-Dist: trl==0.9.6; extra == "smartsearch-policy"
Requires-Dist: torchdata==0.11.0; extra == "smartsearch-policy"
Requires-Dist: tyro==0.8.14; extra == "smartsearch-policy"
Requires-Dist: numpy==1.26.4; extra == "smartsearch-policy"
Requires-Dist: pyarrow==21.0.0; extra == "smartsearch-policy"
Requires-Dist: omegaconf==2.3.0; extra == "smartsearch-policy"
Requires-Dist: safetensors==0.6.2; extra == "smartsearch-policy"
Requires-Dist: sentencepiece==0.2.1; extra == "smartsearch-policy"
Requires-Dist: PyYAML==6.0.2; extra == "smartsearch-policy"
Requires-Dist: einops==0.8.1; extra == "smartsearch-policy"
Requires-Dist: matplotlib==3.10.6; extra == "smartsearch-policy"
Requires-Dist: nltk==3.9.1; extra == "smartsearch-policy"
Requires-Dist: jieba==0.42.1; extra == "smartsearch-policy"
Requires-Dist: rouge-chinese==1.0.3; extra == "smartsearch-policy"
Requires-Dist: protobuf==5.29.5; extra == "smartsearch-policy"
Requires-Dist: tiktoken==0.9.0; extra == "smartsearch-policy"
Requires-Dist: fire==0.7.1; extra == "smartsearch-policy"
Requires-Dist: wheel==0.45.1; extra == "smartsearch-policy"
Requires-Dist: ninja==1.13.0; extra == "smartsearch-policy"
Provides-Extra: smartsearch-grpo
Requires-Dist: torch==2.6.0; extra == "smartsearch-grpo"
Requires-Dist: torchvision==0.21.0; extra == "smartsearch-grpo"
Requires-Dist: torchaudio==2.6.0; extra == "smartsearch-grpo"
Requires-Dist: transformers==4.51.1; extra == "smartsearch-grpo"
Requires-Dist: vllm==0.8.4; extra == "smartsearch-grpo"
Requires-Dist: ray[default]==2.47.1; extra == "smartsearch-grpo"
Requires-Dist: tensordict==0.6.2; extra == "smartsearch-grpo"
Requires-Dist: hydra-core==1.3.2; extra == "smartsearch-grpo"
Requires-Dist: omegaconf==2.3.0; extra == "smartsearch-grpo"
Requires-Dist: antlr4-python3-runtime==4.9.3; extra == "smartsearch-grpo"
Requires-Dist: numpy==1.26.4; extra == "smartsearch-grpo"
Requires-Dist: torchdata==0.11.0; extra == "smartsearch-grpo"
Requires-Dist: datasets==4.0.0; extra == "smartsearch-grpo"
Requires-Dist: pyarrow==21.0.0; extra == "smartsearch-grpo"
Requires-Dist: pandas==2.3.2; extra == "smartsearch-grpo"
Requires-Dist: accelerate==1.9.0; extra == "smartsearch-grpo"
Requires-Dist: codetiming==1.4.0; extra == "smartsearch-grpo"
Requires-Dist: einops==0.8.1; extra == "smartsearch-grpo"
Requires-Dist: safetensors==0.6.2; extra == "smartsearch-grpo"
Requires-Dist: tqdm==4.67.1; extra == "smartsearch-grpo"
Requires-Dist: requests==2.32.5; extra == "smartsearch-grpo"
Requires-Dist: PyYAML==6.0.2; extra == "smartsearch-grpo"
Requires-Dist: packaging==25.0; extra == "smartsearch-grpo"
Requires-Dist: ninja==1.13.0; extra == "smartsearch-grpo"
Requires-Dist: wheel==0.45.1; extra == "smartsearch-grpo"
Requires-Dist: jieba==0.42.1; extra == "smartsearch-grpo"
Requires-Dist: langid==1.1.6; extra == "smartsearch-grpo"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: coverage[toml]>=7.6; extra == "dev"
Requires-Dist: pytest>=8.3; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ir-measures<0.5,>=0.4.1; extra == "dev"
Requires-Dist: pyarrow<24,>=18; extra == "dev"
Requires-Dist: requests<3,>=2.32; extra == "dev"
Requires-Dist: rouge-score<0.2,>=0.1.2; extra == "dev"
Requires-Dist: ruff==0.12.5; extra == "dev"
Requires-Dist: scikit-learn<2,>=1.4; extra == "dev"
Provides-Extra: compression
Requires-Dist: llmlingua==0.2.2; extra == "compression"
Provides-Extra: llmlingua2-fit
Requires-Dist: llmlingua==0.2.2; extra == "llmlingua2-fit"
Requires-Dist: torch<3,>=2.6; extra == "llmlingua2-fit"
Requires-Dist: transformers<6,>=4.51; extra == "llmlingua2-fit"
Requires-Dist: spacy==3.8.7; extra == "llmlingua2-fit"
Requires-Dist: tensorboard==2.20.0; extra == "llmlingua2-fit"
Requires-Dist: numpy<2,>=1.26; extra == "llmlingua2-fit"
Requires-Dist: scikit-learn<2,>=1.4; extra == "llmlingua2-fit"
Requires-Dist: safetensors<1,>=0.5; extra == "llmlingua2-fit"
Provides-Extra: benchmarks
Requires-Dist: pyarrow<24,>=18; extra == "benchmarks"
Provides-Extra: clariq
Requires-Dist: pandas<3,>=2.1; extra == "clariq"
Requires-Dist: scikit-learn<2,>=1.4; extra == "clariq"
Provides-Extra: reformer
Requires-Dist: pandas<3,>=2.1; extra == "reformer"
Provides-Extra: reformer-fit
Requires-Dist: numpy<3,>=1.26; extra == "reformer-fit"
Requires-Dist: pandas<3,>=2.1; extra == "reformer-fit"
Requires-Dist: requests<3,>=2.32; extra == "reformer-fit"
Requires-Dist: tqdm<5,>=4.66; extra == "reformer-fit"
Provides-Extra: recomp-fit
Requires-Dist: torch==1.13.0; extra == "recomp-fit"
Requires-Dist: torchvision==0.14.0; extra == "recomp-fit"
Requires-Dist: sentence-transformers==2.2.2; extra == "recomp-fit"
Requires-Dist: transformers==4.24.0; extra == "recomp-fit"
Requires-Dist: tokenizers==0.13.2; extra == "recomp-fit"
Requires-Dist: huggingface-hub==0.19.4; extra == "recomp-fit"
Requires-Dist: numpy==1.26.4; extra == "recomp-fit"
Requires-Dist: pandas==1.5.3; extra == "recomp-fit"
Requires-Dist: safetensors==0.5.3; extra == "recomp-fit"
Provides-Extra: recomp-seq2seq-fit
Requires-Dist: torch==1.13.0; extra == "recomp-seq2seq-fit"
Requires-Dist: transformers==4.24.0; extra == "recomp-seq2seq-fit"
Requires-Dist: tokenizers==0.13.2; extra == "recomp-seq2seq-fit"
Requires-Dist: numpy==1.26.4; extra == "recomp-seq2seq-fit"
Requires-Dist: datasets==2.14.7; extra == "recomp-seq2seq-fit"
Requires-Dist: pyarrow==14.0.2; extra == "recomp-seq2seq-fit"
Requires-Dist: fsspec==2023.10.0; extra == "recomp-seq2seq-fit"
Requires-Dist: huggingface-hub==0.19.4; extra == "recomp-seq2seq-fit"
Requires-Dist: nltk==3.9.2; extra == "recomp-seq2seq-fit"
Requires-Dist: rouge==1.0.1; extra == "recomp-seq2seq-fit"
Requires-Dist: safetensors==0.5.3; extra == "recomp-seq2seq-fit"
Requires-Dist: sentencepiece==0.2.1; extra == "recomp-seq2seq-fit"
Provides-Extra: adaptive-rag-fit
Requires-Dist: torch==1.13.0; extra == "adaptive-rag-fit"
Requires-Dist: transformers==4.28.1; extra == "adaptive-rag-fit"
Requires-Dist: tokenizers==0.13.3; extra == "adaptive-rag-fit"
Requires-Dist: accelerate==0.15.0; extra == "adaptive-rag-fit"
Requires-Dist: numpy==1.26.4; extra == "adaptive-rag-fit"
Requires-Dist: datasets==2.14.7; extra == "adaptive-rag-fit"
Requires-Dist: pyarrow==14.0.2; extra == "adaptive-rag-fit"
Requires-Dist: fsspec==2023.10.0; extra == "adaptive-rag-fit"
Requires-Dist: huggingface-hub==0.19.4; extra == "adaptive-rag-fit"
Requires-Dist: nltk==3.9.2; extra == "adaptive-rag-fit"
Requires-Dist: safetensors==0.5.3; extra == "adaptive-rag-fit"
Requires-Dist: sentencepiece==0.2.1; extra == "adaptive-rag-fit"
Requires-Dist: jsonlines==4.0.0; extra == "adaptive-rag-fit"
Provides-Extra: plan-and-budget
Requires-Dist: numpy==1.26.4; extra == "plan-and-budget"
Provides-Extra: hyde-native
Requires-Dist: numpy<3,>=1.26; extra == "hyde-native"
Provides-Extra: infocqr-student
Requires-Dist: torch<3,>=2.6; extra == "infocqr-student"
Requires-Dist: transformers<5,>=4.51; extra == "infocqr-student"
Requires-Dist: sentencepiece<0.3,>=0.2; extra == "infocqr-student"
Requires-Dist: safetensors<1,>=0.5; extra == "infocqr-student"
Provides-Extra: llmcompiler
Requires-Dist: langchain==0.2.6; extra == "llmcompiler"
Requires-Dist: langchain-community==0.2.6; extra == "llmcompiler"
Requires-Dist: openai==1.3.7; extra == "llmcompiler"
Requires-Dist: tiktoken==0.5.2; extra == "llmcompiler"
Provides-Extra: decomp
Requires-Dist: torch==1.13.0; extra == "decomp"
Requires-Dist: transformers==4.24.0; extra == "decomp"
Requires-Dist: numpy==1.26.4; extra == "decomp"
Requires-Dist: jsonnet==0.21.0; extra == "decomp"
Requires-Dist: nltk==3.9.2; extra == "decomp"
Requires-Dist: openai==0.28.1; extra == "decomp"
Requires-Dist: diskcache==5.6.3; extra == "decomp"
Requires-Dist: python-dateutil==2.9.0.post0; extra == "decomp"
Requires-Dist: requests==2.32.5; extra == "decomp"
Provides-Extra: acon
Requires-Dist: requests<3,>=2.32; extra == "acon"
Requires-Dist: jinja2<4,>=3.1; extra == "acon"
Requires-Dist: tiktoken<1,>=0.9; extra == "acon"
Provides-Extra: acon-fit
Requires-Dist: requests<3,>=2.32; extra == "acon-fit"
Requires-Dist: jinja2<4,>=3.1; extra == "acon-fit"
Requires-Dist: tiktoken<1,>=0.9; extra == "acon-fit"
Requires-Dist: numpy<3,>=1.26; extra == "acon-fit"
Requires-Dist: openai<3,>=1.50; extra == "acon-fit"
Requires-Dist: PyYAML<7,>=6; extra == "acon-fit"
Requires-Dist: msal<2,>=1.30; extra == "acon-fit"
Requires-Dist: tqdm<5,>=4.66; extra == "acon-fit"
Provides-Extra: ace
Requires-Dist: numpy<3,>=1.26; extra == "ace"
Requires-Dist: openai<3,>=1.50; extra == "ace"
Requires-Dist: python-dotenv<2,>=1.2; extra == "ace"
Requires-Dist: tiktoken<1,>=0.12; extra == "ace"
Provides-Extra: ircot
Requires-Dist: numpy==1.26.4; extra == "ircot"
Requires-Dist: jsonnet==0.21.0; extra == "ircot"
Requires-Dist: transformers==4.24.0; extra == "ircot"
Requires-Dist: spacy==3.4.1; extra == "ircot"
Requires-Dist: openai==0.28.1; extra == "ircot"
Requires-Dist: diskcache==5.6.3; extra == "ircot"
Requires-Dist: nltk==3.9.2; extra == "ircot"
Requires-Dist: requests==2.32.5; extra == "ircot"
Requires-Dist: rapidfuzz<4,>=3; extra == "ircot"
Requires-Dist: ftfy<7,>=6; extra == "ircot"
Requires-Dist: python-dateutil<3,>=2.8; extra == "ircot"
Requires-Dist: tqdm<5,>=4.66; extra == "ircot"
Provides-Extra: evaluation
Requires-Dist: ir-measures<0.5,>=0.4.1; extra == "evaluation"
Requires-Dist: rouge-score<0.2,>=0.1.2; extra == "evaluation"
Provides-Extra: longbench
Requires-Dist: jieba==0.42.1; extra == "longbench"
Requires-Dist: rouge==1.0.1; extra == "longbench"
Requires-Dist: fuzzywuzzy==0.18.0; extra == "longbench"
Provides-Extra: dense-retrieval
Requires-Dist: sentence-transformers<6,>=3.0; extra == "dense-retrieval"
Requires-Dist: transformers<6,>=4.51; extra == "dense-retrieval"
Provides-Extra: selectors
Requires-Dist: scikit-learn<2,>=1.4; extra == "selectors"
Provides-Extra: mce-text
Requires-Dist: openai<3,>=1.50; extra == "mce-text"
Requires-Dist: httpx<1,>=0.27; extra == "mce-text"
Requires-Dist: python-dotenv<2,>=1.2; extra == "mce-text"
Provides-Extra: paper
Requires-Dist: matplotlib<4,>=3.8; extra == "paper"
Requires-Dist: numpy<3,>=1.26; extra == "paper"
Requires-Dist: pandas<3,>=2.1; extra == "paper"
Requires-Dist: scikit-learn<2,>=1.4; extra == "paper"
Provides-Extra: local
Requires-Dist: torch>=2.2; extra == "local"
Requires-Dist: transformers>=4.40; extra == "local"
Provides-Extra: qrag
Requires-Dist: datasets<5,>=3; extra == "qrag"
Requires-Dist: hydra-core<2,>=1.3; extra == "qrag"
Requires-Dist: nltk<4,>=3.9; extra == "qrag"
Requires-Dist: numpy<3,>=1.26; extra == "qrag"
Requires-Dist: omegaconf<3,>=2.3; extra == "qrag"
Requires-Dist: rotary-embedding-torch<1,>=0.8; extra == "qrag"
Requires-Dist: sortedcontainers<3,>=2.4; extra == "qrag"
Requires-Dist: torch>=2.2; extra == "qrag"
Requires-Dist: transformers<6,>=4.51; extra == "qrag"
Provides-Extra: qrag-fit
Requires-Dist: datasets<5,>=3; extra == "qrag-fit"
Requires-Dist: hydra-core<2,>=1.3; extra == "qrag-fit"
Requires-Dist: nltk<4,>=3.9; extra == "qrag-fit"
Requires-Dist: numpy<3,>=1.26; extra == "qrag-fit"
Requires-Dist: omegaconf<3,>=2.3; extra == "qrag-fit"
Requires-Dist: rotary-embedding-torch<1,>=0.8; extra == "qrag-fit"
Requires-Dist: sortedcontainers<3,>=2.4; extra == "qrag-fit"
Requires-Dist: torch<3,>=2.6; extra == "qrag-fit"
Requires-Dist: transformers<6,>=4.51; extra == "qrag-fit"
Requires-Dist: safetensors<1,>=0.5; extra == "qrag-fit"
Requires-Dist: tensorboard<3,>=2.18; extra == "qrag-fit"
Provides-Extra: r2ag-fit
Requires-Dist: torch<3,>=2.6; extra == "r2ag-fit"
Requires-Dist: transformers<6,>=5.15; extra == "r2ag-fit"
Requires-Dist: sentence-transformers<6,>=5; extra == "r2ag-fit"
Requires-Dist: numpy<2,>=1.26; extra == "r2ag-fit"
Requires-Dist: accelerate<2,>=1.10; extra == "r2ag-fit"
Requires-Dist: bitsandbytes==0.49.2; extra == "r2ag-fit"
Requires-Dist: safetensors<1,>=0.5; extra == "r2ag-fit"
Requires-Dist: kernels==0.16.0; extra == "r2ag-fit"
Provides-Extra: process-monitoring
Requires-Dist: psutil>=5.9; extra == "process-monitoring"
Provides-Extra: gpu-monitoring
Requires-Dist: psutil>=5.9; extra == "gpu-monitoring"
Requires-Dist: nvidia-ml-py>=12; extra == "gpu-monitoring"
Provides-Extra: yaml
Requires-Dist: PyYAML>=6.0; extra == "yaml"
Provides-Extra: querygym
Requires-Dist: PyYAML>=6.0; extra == "querygym"
Requires-Dist: tqdm>=4.66; extra == "querygym"
Dynamic: license-file

# AgentInputLab

A Python toolkit and typed JavaScript client for composing and evaluating input interventions for LLM agents.

This branch contains reusable library code, worker adapters, synthetic tests and documentation. It contains no paper results, experiment logs, datasets, trained weights or private execution configuration. It starts a new Git history: do not make the entire historical research repository public to publish this branch.

## Install

The commands below work without GitHub access. The source distribution also
includes `docs/getting-started.md` with a real HTTP backend example and troubleshooting.

Python 3.10+; optional model dependencies have their own Python/platform constraints.

```sh
python -m pip install agentinputlab==0.1.0a2
python -m agentinputlab --version
python -m agentinputlab doctor --offline --json
python -m agentinputlab smoke --json
```

To obtain the public source and included documentation from PyPI:

```sh
python -m pip download --no-deps --no-binary=agentinputlab agentinputlab==0.1.0a2
tar -xzf agentinputlab-0.1.0a2.tar.gz
cd agentinputlab-0.1.0a2
python -m pip install .
```

Maintainers with repository access can instead use the Git checkout
(the research repository remains private):

```sh
git clone --single-branch --branch release/toolkit-public https://github.com/Data-Designer/AgentInputLab.git
cd AgentInputLab
python -m pip install .
agentinputlab doctor --offline
agentinputlab smoke --json
```

The Python distribution is an initial alpha. The JavaScript SDK remains source-only while npm publication is deferred. To build local Python and SDK artifacts:

```sh
python -m pip install build
python -m build
python -m pip install dist/agentinputlab-0.1.0a2-py3-none-any.whl
cd packages/sdk
npm ci
npm test
npm pack
# From a JavaScript application:
npm install /absolute/path/to/agentinputlab-sdk-0.1.0-alpha.1.tgz
```

## Python: apply a real intervention

```python
from agentinputlab import FrozenAgentState, InterventionContext
from agentinputlab.api import create_intervention, run_intervention

method = create_intervention("plan.plan_and_solve.ps_prompt")
result = run_intervention(method, FrozenAgentState(query="Find a suitable flight"),
                          InterventionContext(seed=17))
print(result["state"]["instruction"])
```

This executes the Plan-and-Solve prompt intervention. It is not an LLM response or a scored benchmark result. For model-driven methods, supply an explicit backend, retriever or external worker in `InterventionContext`; constructors retain their documented method-specific parameters. See [real execution](docs/real-execution.md).

```python
from agentinputlab.api import catalog
from agentinputlab.registry import AlgorithmRegistry

print(catalog()["benchmarks"])
registry = AlgorithmRegistry.default()
for method, profile in registry.list_releases():
    print(method.method_id, profile.id, profile.status.value, profile.blocking_reasons)
```

The catalog exposes 27 method identities and 31 benchmark entries, including ToolTalk and datasets outside the paper's reporting subset. Choose a release profile and provision its declared code, checkpoints, environment and native scorer. Profile registration and real execution are separate compatibility dimensions; see [validation and profile prerequisites](docs/validation.md). Composite agents retain their native interfaces.

For Rewrite-Retrieve-Read (RRR), start with
[`rewrite.rrr.common_support_prompt`](docs/rrr-controlled.md): the controlled
prompt adapter uses your configured backbone and retriever for the
rewrite → retrieve → reader chain. Author warm-up/PPO checkpoints are separate,
optional external profiles.

For offline optimization, see [Q-RAG value-policy training](docs/qrag-training.md)
and [R²AG reader-aligned training and generation](docs/r2ag-training.md). These
recipes save fitted artifact identities and separate training costs from
subsequent inference.

## JavaScript / TypeScript

The SDK connects to the same Python execution core; it does not reimplement algorithms. In Python, configure a server with explicit profile factories and dependency contexts. The CLI exposes only NO_OP and Plan-and-Solve by default:

```sh
# Set a newly generated local token of at least 24 characters in your shell.
export AGENTINPUTLAB_API_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
agentinputlab-serve --port 8765
```

```typescript
import { AgentInputLab } from '@agentinputlab/sdk';
const client = new AgentInputLab({ token: process.env.AGENTINPUTLAB_API_TOKEN! });
const inventory = await client.catalog();
const result = await client.intervene({
  release_id: 'plan.plan_and_solve.ps_prompt',
  state: { query: 'Find a suitable flight', budget: { max_model_calls: 8, max_output_tokens: 4096 } },
  seed: 17,
});
console.log(result.state);
```

The bundled HTTP server is authenticated and loopback-only. It is a development bridge, not a public multi-tenant hosting service. Browser CORS is intentionally disabled. Do not expose its token in browser bundles. See [API contract](docs/api.md).

## Tests versus real measurements

```sh
python -m pip install pytest
pytest
python tools/check_distribution.py dist/*.whl dist/*.tar.gz
python tools/compatibility_inventory.py --output /tmp/agentinputlab-compatibility.json
```

Offline tests exercise algorithm behavior with explicit synthetic fixtures, transport, budgets, typed failures and worker contracts. The compatibility inventory checks every registered method, benchmark and requested backbone identity; it does not run models and labels untested cells as untested. Model names are user-configured, not hardcoded as a supported-model allowlist.

Real acceptance requires licensed data, pinned assets, an actual serving endpoint and the benchmark's native scorer. A patch, a synthetic fixture, a mock HTTP reply or an imported adapter is never an official score. See the staged [validation policy](docs/validation.md).

## License

MIT for this repository's code. External dependencies retain their own licenses; consult `THIRD_PARTY_NOTICES.md` before downloading or distributing them. Registry publication follows the [acceptance and ownership checks](PUBLISHING.md).
