File size: 3,957 Bytes
77da5ce | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 | # task.py — Task Schema Reference
`core/task.py` — Dataclass definitions for the LifeStack long-horizon episode schema.
---
## Overview
A `Task` is the complete specification of a single episode. It defines what the agent
must achieve, how the world can change around it, and what routes are available.
---
## Dataclasses
### `Task`
```python
@dataclass
class Task:
id: str # Unique task identifier
domain: str # e.g. "flight_crisis", "code_merge_crisis"
goal: str # Human-readable goal description
constraints: dict # e.g. {"budget_max": 800, "deadline_step": 10}
hidden_state: dict # Keys not visible without inspect
mutable_world: dict # Keys that can change during the episode
visible_world: dict # Keys always visible in the observation
success_conditions: list[dict] # [{key, value}] — all must be met
failure_conditions: list[dict] # [{key, value}] — any triggers failure
event_schedule: list[ExoEvent] # Deterministic/probabilistic events
viable_routes: list[Route] # Available action paths
milestones: list[Milestone] # Progress checkpoints
horizon: int # Max steps per episode
difficulty: int # 1–5 scale
domain_metadata: dict # Free-form extra info (e.g. {"story": "..."})
```
### `Route`
```python
@dataclass
class Route:
id: str
name: str
description: str
required_action_types: list[str] # e.g. ["communicate", "spend"]
preconditions: dict # World/hidden state conditions that must be true
consequences: dict # World state mutations on success
closes_routes: list[str] # Route IDs that become unavailable after this
milestones_unlocked: list[str] # Milestone IDs unlocked on route success
final_reward: float # Bonus reward on route completion
```
### `Milestone`
```python
@dataclass
class Milestone:
id: str
description: str
condition_key: str # World/hidden state key to check
condition_value: Any # Value it must equal for milestone to be met
reward: float # Reward added when milestone is first reached
```
### `ExoEvent`
```python
@dataclass
class ExoEvent:
step: int # Step at which to fire (-1 = probabilistic each step)
probability: float # Firing probability if step == -1
id: str
description: str
world_mutation: dict # Applied to mutable_world on fire
hidden_state_mutation: dict # Applied to hidden_state on fire
closes_routes: list[str] # Routes closed when this event fires
```
---
## Built-in Tasks
| Class | Domain | Description |
|---|---|---|
| `FlightCrisisTask` | `flight_crisis` | Cancelled flight — rebook or work from lounge |
---
## Creating a Custom Task
```python
from core.task import Task, Route, Milestone, ExoEvent
my_task = Task(
id="my_task",
domain="my_domain",
goal="Do the thing",
constraints={"budget_max": 500, "deadline_step": 8},
hidden_state={"secret_key": True},
mutable_world={},
visible_world={"public_info": "visible"},
success_conditions=[{"key": "done", "value": True}],
failure_conditions=[],
event_schedule=[],
viable_routes=[
Route(id="r1", name="Route One", description="...",
required_action_types=["execute"],
preconditions={}, consequences={"done": True},
closes_routes=[], milestones_unlocked=[], final_reward=1.0)
],
milestones=[],
horizon=20,
difficulty=2,
domain_metadata={"story": "A short story about the crisis."}
)
```
Then pass it to the environment:
```python
env = LifeStackEnv()
obs = env.reset(task=my_task)
```
---
## Change Log
| Date | Change |
|---|---|
| 2026-04-23 | Initial doc created |
|