# Agent-Human Work Ledger Service

## PURPOSE
Two of the seven pieces the video says no platform has shipped together are the ledger
("most work in businesses never gets tracked anywhere") and the admin panel (managing
humans and agents, access, monitoring token usage and cost). This service implements
both: a SQLAlchemy-backed API that records every work event produced by a human or an
agent — who did it, which project it belongs to, what files were created, and a link to
the session — plus a token-usage and cost view an admin can query.

## WHY THIS MATTERS
It teaches the transcript's most concrete engineering idea: a shared, queryable record.
The video says that once work is tracked he can "ask what is happening with this project"
and have agents query the ledger. Modelling that as rows in a database is exactly the
skill that separates a demo from a real AI-native system.

## HOW TO BUILD
SQLAlchemy 2.0 declarative models plus FastAPI for the HTTP surface, and httpx as an
async client for a "vendor status" integration (for example polling a platform's
health endpoint). Key models and relationship:

```python
class Actor(Base):
    __tablename__ = "actors"
    id: Mapped[int] = mapped_column(primary_key=True)
    kind: Mapped[str]  # "human" | "agent"
    name: Mapped[str]

class WorkEvent(Base):
    __tablename__ = "work_events"
    id: Mapped[int] = mapped_column(primary_key=True)
    actor_id: Mapped[int] = mapped_column(ForeignKey("actors.id"))
    project: Mapped[str]
    artifact: Mapped[str | None]
    session_link: Mapped[str | None]
    tokens: Mapped[int] = mapped_column(default=0)
    cost_usd: Mapped[float] = mapped_column(default=0.0)
```

Expose `POST /events`, `GET /projects/{name}/events`, and `GET /admin/usage`. Use httpx
in a small `vendor_status` coroutine so the ledger can note which platform each agent
runs on.

## WHEN TO USE IN PRODUCTION
Ideal for an internal platform team or an agency that must prove what agents did for
audit and billing; it pairs with the video's bonus that OpenAI credits come at "plain
API price," letting you reconcile spend. Do NOT use it to store secrets or raw customer
documents — the data layer is a separate concern; and skip it if your only need is
notifications, which a logging tool already covers.

## HOW IT HELPS STUDENTS
You learn SQLAlchemy ORM modelling, foreign keys and relationships, session management,
async httpx integration, and designing admin/usage endpoints. This is the day-to-day of
backend engineering, and it directly mirrors the transcript's ledger and admin-panel
pieces.

## STARTER CODE
See `starter/main.py` — real SQLAlchemy models, an httpx helper, and FastAPI routes with
`# TODO` markers for migrations and auth.
