# Accountability Ledger Service (SQLAlchemy + httpx)

## PURPOSE
"AI will never be accountable. I will be accountable." That sentence is a data-modelling requirement. This service is a durable ledger that records every AI-assisted answer, the model or agent that produced it, and the named human who accepted responsibility for releasing it. It pairs SQLAlchemy persistence with an httpx client that calls an upstream plain-language analytics endpoint (a Genie-style API stand-in), so accountability survives restarts and can be audited months later.

## WHY THIS MATTERS
The transcript distinguishes AI's "speed and scale" from the human's "judgment calls" and "decisions." A ledger makes that distinction permanent evidence: each row has an immutable `ai_proposal` and a separate `human_decision` field with an approver identity and timestamp. When an auditor or regulator asks "who was accountable for this number?", the answer is a query, not a memory.

## HOW TO BUILD
Use SQLAlchemy 2.0 declarative models with a SQLite URL, an httpx Client that posts questions to the upstream analytics service, and a small service layer that writes ledger rows. Three tables: `questions`, `ai_answers`, and `accountability_records`.

```python
class AccountabilityRecord(Base):
    __tablename__ = "accountability_records"
    id: Mapped[int] = mapped_column(primary_key=True)
    ai_answer_id: Mapped[int] = mapped_column(ForeignKey("ai_answers.id"))
    accountable_person: Mapped[str]              # never the model
    decision: Mapped[str]                        # approved | rejected | escalated
    rationale: Mapped[str] = mapped_column(default="")
    decided_at: Mapped[datetime]


def ask_upstream(client: httpx.Client, question: str) -> dict:
    resp = client.post("/ask", json={"question": question, "requester": "svc"})
    resp.raise_for_status()
    return resp.json()
```

## WHEN TO USE IN PRODUCTION
Use it wherever AI-assisted decisions touch money, security, compliance, or customer commitments and you need an append-only audit trail with a real human name attached. It fits financial reporting copilots, security-posture assistants, and regulated analytics. Do **not** use it as the real-time answer path — it is an audit and accountability layer, not a low-latency gateway. Avoid it for purely creative or exploratory AI use where no decision is being sanctioned, since the overhead earns nothing there. Also skip it if your organisation has no clear human owner to record; an empty approver field defeats the purpose.

## HOW IT HELPS STUDENTS
Students learn SQLAlchemy 2.0 typed models, relationships and foreign keys, session lifecycle, and httpx client usage with proper status handling. Most importantly they practise schema design for auditability — immutable AI proposals separated from human decisions — which is a recurring pattern in enterprise AI governance platforms.

## STARTER CODE
`starter/main.py` defines the engine, models, session factory, httpx call stub, and a `record_decision` service function, with `# TODO` markers for migrations, auth, and retention policy.
