Allocator API (FastAPI on Palisades)

Base service: allocator_api
Typical deployment: behind uvicorn, reachable on Palisades (public subnet).

All endpoints require a simple header token:

x-api-token: <shared-secret>

(e.g. devtoken123 in your dev setup).

Models

SubmitAllocReq

Pydantic v2 model (fields reflect your current worker implementation):

class AllocatorJobSpec(BaseModel):
    household_id: str
    objective: str = "custom"
    n_sims: int = Field(gt=0, default=3000)
    n_jobs: int = Field(gt=0, default=8)
    local_iters: int = Field(gt=0, default=4)
    grid_step: float = Field(gt=0, default=0.1)
    start_crt: float
    start_tax: float
    years: int = Field(gt=0, default=30)
    payout_rate: float = Field(gt=0, default=0.085)


class SubmitAllocReq(BaseModel):
    tenant: str = "nts"
    dry_run: bool = False
    idem_hint: str | None = None
    job: AllocatorJobSpec

SubmitAllocAck

class SubmitAllocAck(BaseModel):
    status: str                    # "enqueued"
    job_id: str                    # Redis stream id
    idem_key: str                  # derived or idem_hint
    message: str                   # "Queued"