homeOS: Family Action Inbox

Turn household papers and messages into structured, reviewable family action candidates—while keeping humans in control of what becomes official.

Comment

Inspiration

Families receive a constant stream of information through school handouts, PDFs, chat messages, email, and verbal reminders.

The difficult part is not simply storing those documents. The real questions are:

  • Who does this concern?
  • What may need to be done?
  • Is there a deadline or event date?
  • What information is still unclear?
  • Has someone reviewed it?
  • Where is the original paper?

In a household with multiple children, important information can remain in school bags, on desks, or in shared spaces until nobody knows whether it was reviewed or handled.

We built homeOS: Family Action Inbox to turn unstructured household information into structured, reviewable action candidates while keeping humans in control of what becomes official.

What it does

homeOS implements a controlled workflow:

household input
→ AI-generated candidate proposals
→ strict validation
→ pending candidates
→ human review
→ explicit confirm or reject

The central rule is:

AI and external intake channels may propose actions, but they cannot directly create official family obligations.

GPT-5.6 interprets an unstructured household message and returns structured proposals containing:

  • relevant household subject IDs
  • a candidate title
  • explanatory details
  • evidence from the source
  • uncertainties that still require human judgment

The output is validated against a strict Structured Outputs schema and a separate application DTO.

Unknown fields are rejected. Subject IDs must belong to an explicit allowlist. Invalid or incomplete responses fail before candidates are written.

A successful interpretation still creates only pending candidates. A separate human action is required to confirm or reject them.

How we built it

The public prototype is implemented in Python as a command-line application with a candidate review workflow and append-only local records.

The main components are:

  • household text intake
  • deterministic candidate validation
  • GPT-5.6 Structured Outputs integration
  • a dedicated LLM response DTO
  • strict unknown-field rejection
  • household subject allowlist validation
  • candidate creation
  • explicit confirm and reject commands
  • separation between pending candidates and confirmed items
  • audit-oriented work logs
  • automated failure-path and confirmation-boundary tests

The GPT-5.6 response contract uses these required fields:

subject_ids
title
details_text
evidence
uncertainties

The adapter performs a deterministic conversion:

details_text
→ ProposalInput.details
→ Candidate.details

It does not summarize the text, infer a responsible person, create a schedule, make a confirmation decision, or trigger another household action.

The domain model remains independent of the OpenAI-specific DTO. This keeps the LLM integration at the system boundary and preserves the existing confirmation workflow.

Codex was used for bounded implementation, repository analysis, tests, SDK compatibility corrections, live-verification preparation, and documentation updates.

Claude was used as an independent architecture and safety auditor. Its review focused on DTO separation, deterministic conversion, strict schema alignment, subject allowlists, zero-write failure behavior, confirmation boundaries, and public-repository safety.

Live GPT-5.6 verification

The live GPT-5.6 integration was verified through:

  • a successful OpenAI API response
  • acceptance of the strict Structured Outputs schema
  • successful DTO validation
  • two structured proposals
  • two returned Candidate IDs

No confirm or reject command was executed during the live request.

The specific live-response store could not be re-read after the run because a temporary runtime directory did not persist. Therefore, we do not claim complete live end-to-end persistence verification.

Cross-process persistence behavior is covered separately by automated CLI tests.

Challenges we ran into

Unstructured household information

A single school notice can contain an event, required items, a response deadline, an optional activity, and several child-specific conditions.

One source does not necessarily correspond to one action candidate.

Subject identification

The model must not invent family-member identifiers.

We therefore pass an explicit subject allowlist to the model and validate all returned subject IDs before writing candidates.

When the subject cannot be identified safely, the proposal can use an empty subject list and record the uncertainty for human review.

LLM and domain boundaries

The internal domain model allows flexible JSON-compatible details, while the LLM contract needs a schema that Structured Outputs can enforce reliably.

We solved this by introducing a dedicated LLM DTO with a plain details_text field and converting it deterministically into the existing domain input.

Safe failure

An invalid AI response must not partially update household records.

Malformed JSON, unknown fields, missing required properties, invalid subject IDs, and incomplete responses are rejected before candidate creation.

Human authority

Human review could not be only a user-interface convention.

The interpretation path is structurally unable to create confirmation decisions or confirmed household items. Confirmation requires a separate explicit command.

Privacy

Real household messages may contain names, schedules, contact details, addresses, and information about children.

The public repository and demonstration use synthetic data. API keys, raw responses, runtime records, private audit reports, and real household data are excluded.

Scope

The broader homeOS vision includes physical document intake, OCR, responsibility assignment, notifications, calendars, and household communication.

For Build Week, we narrowed the project to one auditable workflow:

unstructured household text
→ GPT-5.6 proposal
→ strict validation
→ pending candidate
→ human decision

Accomplishments that we're proud of

We are proud that homeOS is not only a prompt demonstration.

The public prototype includes:

  • a working candidate review lifecycle
  • a strict GPT-5.6 Structured Outputs contract
  • deterministic DTO-to-domain conversion
  • subject allowlist enforcement
  • unknown-field rejection
  • zero-write failure paths
  • an explicit human confirmation boundary
  • public-safe technical work logs
  • 45 passing automated tests
  • a successful live GPT-5.6 response through Candidate ID return
  • independent architecture and safety review

Most importantly, the system is designed to fail safely:

AI can suggest. People decide.

What we learned

The hardest part of household automation is not OCR or task storage.

It is preserving incomplete information without silently turning uncertain interpretations into obligations.

We learned that several concepts must remain separate:

  • who the information concerns
  • who submitted the information
  • what the AI inferred
  • what evidence supports the inference
  • what remains uncertain
  • whether a candidate has been reviewed
  • whether a human has officially confirmed it

We also learned that a good AI integration requires more than a prompt.

The response schema, DTO validation, domain validation, persistence boundary, failure behavior, and human decision path all need to agree.

Independent review was especially useful. Several issues that looked minor—such as unknown response fields, subject-ID context, incomplete API responses, and wording in public documentation—had direct effects on safety and reproducibility.

What's next for homeOS: Family Action Inbox

The immediate next steps are:

  • add a family-friendly review interface
  • support OCR and document-image intake
  • show source evidence and uncertainty more clearly
  • verify the complete live-response persistence path
  • support configurable household subjects
  • improve physical-document references using QR-coded holders
  • package the prototype for easier local installation

Longer-term possibilities include:

  • responsibility assignment
  • reminder and notification routing
  • calendar integration
  • household communication channels
  • local-first privacy classification
  • physical document location support
  • multiple interchangeable LLM providers

The goal is not to automate family decisions.

The goal is to make household obligations visible, reviewable, traceable, and much harder to lose.

Built With

Share this project:

Updates