new: implement environment-free agent-trace generation

AGENTS.md

@@ -14,6 +14,7 @@
 - **Multiple Storage Backends**: Store conversations in JSONL files or SQL databases (SQLite, PostgreSQL, MySQL).
 - **Save in JSONL Format**: Export datasets directly for downstream applications.
 - **Quality Analysis**: Comprehensive dataset quality checks with visualization support.
+- **Environment-Free Agent Traces**: Generate synthetic agent execution trajectories combining ESAT methodology with sub-millisecond local declarative simulation tools (`afterimage.agent_trace`).
 - **Generation Monitoring**: Real-time monitoring of generation metrics with alerts and visualization.
 
 **See @DESIGN.md for the code design and architecture.**

DESIGN.md

@@ -31,6 +31,7 @@ The library is designed around a few core concepts:
 - **Training Version Compatibility Guards**: Demo training requirements constrain `transformers` and `trl` to a compatible range (`transformers>=4.56.2,<5.0.0`, `trl>=0.29.1,<0.30.0`) to avoid runtime API mismatches during `SFTConfig` import and trainer startup. The same stack is declared as the `training` optional extra in `pyproject.toml` (aligned with `examples/demo_ui/training_scripts/requirements.txt`); install with `pip install -e ".[training]"` or `uv sync --extra training` so the Gradio-launched `train.py` subprocess can import `trl` and related packages.
 - **Environment Template Files**: Repository root includes a minimal `.env.example` and local `.env` template for demo runtime and training credentials (`GEMINI_API_KEY`, `DEEPSEEK_API_KEY`, `HF_TOKEN`, optional `HF_HUB_DISABLE_XET`); `.env` is gitignored to keep secrets out of version control.
 - **CLI Interface**: The `afterimage` command provides `generate`, `validate`, and `export` subcommands. Generation is driven by YAML config files that map to Pydantic models in `config.py`. The `export` command converts datasets to ShareGPT, Alpaca, or HuggingFace messages formats.
+- **Agent Trace Dataset Generation**: The `afterimage.agent_trace` subpackage provides environment-free synthetic agent-trace dataset generation combining ESAT methodology with a sub-millisecond local Declarative Tool Simulation Framework and dual-mode observation synthesis (`observation_mode: Literal["faker", "llm"]`, defaulting to `"llm"` as preferred production mode and `"faker"` as experimental). Key components include `SchemaArchitect` (LLM Pydantic response schema generator with static AST verification feedback loop), `SchemaVerifier` (6 structural invariant checks), `DeclarativeEngine` (4-tier fallback generator with parameter echoing annotations `param:<name>`/`echo` and semantic synonym matching), `LLMObservationSynthesizer` (LLM-driven structured observation generation as in original ESAT methodology), `DeclarativeEnvironment` & `DeclarativeTool` (dual-mode observation dispatching + stateful `SimulationContext` persistent entity & account balance deduction tables), `GridTaskSynthesizer` (360-bucket grid + `InverseFrequencySampler` + initial state context synthesizer), `ReActTrajectoryLoop` (multi-turn teacher execution against local tools), `TrajectoryJudge` (9-point LLM quality rubric), and `AsyncAgentTraceGenerator` facade. Explicit Pydantic response classes can be attached to `ToolActionSpec` via `response_model_cls` to bypass LLM schema generation. All subpackage components strictly align with the `afterimage.providers.llm_providers.LLMProvider` interface (`agenerate_content`, `agenerate_structured` with `schema`, and `astart_chat`). Model defaults follow `gemini-3.5-flash-lite` for execution/synthesis and `gemini-3.6-flash` for schema architecture and trajectory judging.
 - **Local Model Support**: The `local` provider wraps the OpenAI-compatible API with local-friendly defaults: no API key required, no rate limiting via SmartKeyPool, extended timeouts (30s connect, 300s request), and clear connection error messages. Works with vLLM, Ollama, and llama.cpp servers.
 
 ## Directory Structure

README.md

@@ -31,6 +31,17 @@ from a single YAML file or a composable Python API.
 
 ## News
 
+### July 26, 2026 — Environment-Free Synthetic Agent Traces (`afterimage.agent_trace`)
+
+**afterimage.agent_trace** combines the **ESAT** pipeline (*Environment-free Synthetic Data Generation for API-Calling Agents*, [arXiv:2607.16900](https://arxiv.org/abs/2607.16900)) with a sub-millisecond local **Declarative Tool Simulation Framework** and **Dual-Mode Observation Generation** (`observation_mode: "faker" | "llm"`). It enables training data generation for API-calling AI agents without pre-building backend applications or databases. Key highlights:
+- **Dual Observation Modes:** Toggle seamlessly between sub-millisecond local execution (`"faker"`, `< 1 ms`, 0 tokens) and LLM-driven structured observation synthesis (`"llm"`, original ESAT paper methodology).
+- **Referential Integrity & Parameter Echoing:** Generator annotations (`param:<name>`, `echo`, `state:account_balance`, `fk:<entity>.<field>`) and explicit Pydantic response models guarantee 100% parameter matching and stateful context mutations.
+- **Static AST Verification:** `SchemaVerifier` checks 6 structural invariants with automatic LLM self-correction feedback loops.
+- **360-Bucket Grid & Inverse Frequency:** Combinatorial task synthesis grid paired with inverse-frequency endpoint sampling.
+- **Trajectory Curation:** Multi-turn ReAct teacher agent interaction (`gemini-3.5-flash-lite`) filtered by a 9-point rubric judge (`gemini-3.6-flash`).
+
+See the [docs](https://afterimage.altai.dev/agent_trace.html) and runnable script [`examples/agent_trace_generator_demo.py`](examples/agent_trace_generator_demo.py).
+
 ### May 13, 2026 — Context2skill
 
 **ctx2skill** is a new method to convert and iteratively optimize large contexts to skills that agents can use, originally proposed in [From context to skills: Can language models learn from context skillfully?](https://arxiv.org/html/2604.27660v1). See the [docs](https://afterimage.altai.dev/context_to_skill_tutorial.html) to learn how to use it.
@@ -86,7 +97,7 @@ Your documents  +  LLM  →  Realistic, diverse, quality-filtered training data
 
 | Category | What's included |
 |---|---|
-| **Generation** | Multi-turn chat · Document-grounded QA · Persona-driven diversity · Structured output · Tool-calling |
+| **Generation** | Multi-turn chat · Document-grounded QA · Persona-driven diversity · Structured output · Tool-calling · Environment-free Agent Traces (ESAT + Declarative Engine) |
 | **Preference Data** | DPO · RLHF · UltraFeedback · Anthropic HH · ORPO |
 | **Quality** | LLM-as-judge · Embedding-based metrics · Auto-improve retries · Composite scoring |
 | **Providers** | Gemini · OpenAI · DeepSeek · OpenRouter · Local (vLLM / Ollama / llama.cpp) |
@@ -169,6 +180,12 @@ afterimage push -c your_config.yaml --repo-id your-org/your-dataset
 afterimage preference -c your_config.yaml
 ```
 
+**Generate environment-free synthetic agent traces:**
+
+```bash
+afterimage agent-trace --app-name "banking_app" -n 10 -o "outputs/agent_trajectories.jsonl"
+```
+
 **Analyze your dataset:**
 
 ```bash
@@ -200,6 +217,38 @@ async def main():
 asyncio.run(main())
 ```
 
+**Environment-free synthetic agent trace generation (`afterimage.agent_trace`):**
+
+```python
+import asyncio
+import os
+from afterimage.agent_trace import AsyncAgentTraceGenerator, ToolActionSpec, ToolParameterSpec
+
+async def main():
+    generator = AsyncAgentTraceGenerator(
+        api_key=os.environ["GEMINI_API_KEY"],
+        architect_model="gemini-3.6-flash",
+        teacher_model="gemini-3.5-flash-lite",
+        judge_model="gemini-3.6-flash",
+    )
+    await generator.register_app_domain(
+        app_name="banking_app",
+        app_description="Customer banking application.",
+        actions=[
+            ToolActionSpec(
+                action_name="get_balance",
+                description="Fetch user account balance.",
+                parameters=[ToolParameterSpec(name="account_id", type="int")],
+                response_model_name="BalanceResponse",
+            )
+        ],
+    )
+    trajectories = await generator.generate(num_trajectories=10, max_turns=5)
+    print(f"Generated {len(trajectories)} agent trajectories.")
+
+asyncio.run(main())
+```
+
 **Document-grounded generation with personas:**
 
 ```python

afterimage/__init__.py

@@ -1,5 +1,6 @@
 import importlib.metadata
 
+from afterimage.agent_trace import AsyncAgentTraceGenerator  # noqa
 from afterimage.async_conversation_generator import AsyncConversationGenerator  # noqa
 from afterimage.callbacks import (
     AndStoppingCallback,  # noqa

afterimage/agent_trace/__init__.py

@@ -0,0 +1,53 @@
+"""
+AfterImage Agent Trace subpackage for environment-free synthetic agent-trace dataset generation.
+"""
+
+from .generator import AsyncAgentTraceGenerator
+from .llm_observation_synthesizer import LLMObservationSynthesizer
+from .schema_architect import SchemaArchitect
+from .simulation_engine import DeclarativeEngine, SimulationContext
+from .task_synthesis import GridTaskSynthesizer, InverseFrequencySampler
+from .tool_environment import DeclarativeEnvironment, DeclarativeTool
+from .trajectory_generator import ReActTrajectoryLoop
+from .trajectory_judge import TrajectoryJudge
+from .types import (
+    AgentTrajectory,
+    AppDomainSpec,
+    GridTaskBucket,
+    JudgeVerdict,
+    ObservationMode,
+    RubricScores,
+    ToolActionSpec,
+    ToolCall,
+    ToolObservation,
+    ToolParameterSpec,
+    TrajectoryTurn,
+)
+from .verifier import SchemaVerifier, VerificationReport
+
+__all__ = [
+    "AsyncAgentTraceGenerator",
+    "LLMObservationSynthesizer",
+    "DeclarativeEngine",
+    "SimulationContext",
+    "DeclarativeEnvironment",
+    "DeclarativeTool",
+    "SchemaArchitect",
+    "SchemaVerifier",
+    "VerificationReport",
+    "GridTaskSynthesizer",
+    "InverseFrequencySampler",
+    "ReActTrajectoryLoop",
+    "TrajectoryJudge",
+    "AgentTrajectory",
+    "AppDomainSpec",
+    "GridTaskBucket",
+    "JudgeVerdict",
+    "ObservationMode",
+    "RubricScores",
+    "ToolActionSpec",
+    "ToolCall",
+    "ToolObservation",
+    "ToolParameterSpec",
+    "TrajectoryTurn",
+]