# Project export: NotAlone

This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small.

## Project metadata

- Hackathon: OpenAI Build Week
- Tagline: When life feels overwhelming, NotAlone builds an AI team around your needs and boundaries, then gives you one manageable next step. Feeling lost should never mean being left alone.
- Devpost: https://devpost.com/software/notalone-vbi4xf
- GitHub: https://github.com/rthgit/notalone-openai-build-week
- Demo: https://web-nine-wheat-83.vercel.app/#/build-week
- Video: https://www.youtube.com/embed/V93QOew-ADU?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent
- Team: 1 GitHub contributor(s) — Christian Quintino De Luca (3 commits)

## Devpost submission (written by the team)

### Inspiration

At least once in our lives, each of us has felt alone and lost. Maybe it lasted a minute. Maybe a night. Maybe much longer. It is that moment when the room suddenly feels too large, the phone too quiet, and even the smallest decision weighs somewhere between the stomach and the chest. I started from a simple, perhaps stubborn idea: we may not be able to prevent every difficult situation, but feeling lost should never mean being left alone. That is where NotAlone was born. I also believe that doing good travels in both directions. It helps the person who receives it, of course, but it changes something inside the person who offers it too. A gesture, a little time, the right words at the right moment: small things, perhaps, but small does not mean insignificant. NotAlone is my attempt to give technology this purpose. Not to replace people. To help people be there.

### What it does

NotAlone listens before it organizes. The person can describe a difficult situation naturally: being stranded abroad, losing documents, facing a family problem, feeling overwhelmed or simply not knowing where to begin. Before creating a plan, NotAlone builds a Human Agency Contract. It understands the person’s current capacity, preferred support style, consent and privacy boundaries. It then creates the smallest useful team of specialized AI agents for that exact situation. The agents examine different parts of the problem, challenge uncertain information and distinguish facts from assumptions. But the person does not receive another heroic forty-seven-step checklist. When your head is already burning, step thirty-eight might as well be on the Moon. NotAlone begins with one reversible, manageable action: the Next Kindest Step. If the person says, “This is too much,” the Living Plan becomes smaller and adapts without forgetting the boundaries that were already expressed. No automatic emergency call, third-party contact or location sharing happens without explicit human approval.

### How we built it

The experience is built with Flutter, with a FastAPI, Python and Pydantic backend. Codex and GPT-5.6 accompanied the project throughout Build Week as an engineering collaborator. They helped inspect the inherited foundation, separate the new Build Week scope, design the human-agency and situation models, implement the dynamic agent runtime, strengthen retries and fallback behavior, create focused tests, verify the Vercel deployment and review the claims shown to judges. The human decisions remained human: the purpose of the product, its name, its boundaries, its consent model, its privacy rules and the actions it must never take by itself. The hosted runtime is honestly attributed. It currently uses trace-confirmed openai/gpt-oss-120b through Groq or a clearly labeled deterministic fallback. It never presents GPT-OSS as GPT-5.6. Challenges The hardest part was not making the AI do more. It was teaching the product when to do less. A person in difficulty does not necessarily need the most complete answer. They need an answer they can actually carry, without being frightened, overwhelmed or pushed beyond their consent. We also needed to make the AI team transparent. NotAlone therefore shows how the agents worked, which execution mode was used, what remains uncertain and where fallback occurred. Accomplishments During Build Week we completed: a working public Flutter and FastAPI application; the Human Agency Contract; situation-specific agents and subagents; independent execution traces; a critic and uncertainty ledger; the capacity-aware Next Kindest Step; Living Plan adaptation through “This is too much”; transparent provider and fallback attribution; focused backend tests, Flutter analysis, widget testing and a production web build.

### What we learned

Intelligence alone does not create trust. Trust comes from admitting uncertainty, asking permission, protecting boundaries and giving people the right to stop. I also learned that the best first action is not always the largest or most impressive one. Sometimes it is simply the step a person can take without their hands beginning to shake. One step. Then another. But not alone.

### What's next

NotAlone can grow through permissioned plugins for trusted-contact handoffs, emergency information, safe destinations, parked-car memory and journey breadcrumbs. The AI may prepare, explain and recommend these actions. The person will continue to decide what is actually executed. NotAlone cannot promise that nobody will ever feel lost again. It carries a different promise: when that moment arrives, we can build something that stays beside them until the first step becomes possible. Doing good does good. In both directions. Links Live demo: https://web-nine-wheat-83.vercel.app Source code: https://github.com/rthgit/notalone-openai-build-week Demo video: https://www.youtube.com/watch?v=V93QOew-ADU

## README (from the GitHub repository)

# NotAlone — A Dynamic AI Swarm for Human Situations

> Your situation. Your boundaries. A plan built around you.

NotAlone turns a complex human situation into one manageable, reversible next
step. Before planning, it creates a Human Agency Contract from the person's
capacity, support preferences, privacy boundaries, and consent. It then builds
the smallest useful team of agents for that exact need, challenges uncertain
claims, and adapts the plan when the person says, “This is too much.”

## Live demo

- App: https://web-nine-wheat-83.vercel.app
- API health: https://backend-mu-rose-49.vercel.app/build-week/health
- Track: **Apps for Your Life**
- License: **MIT**
- Primary Codex `/feedback` Session ID: `019f5d92-1d08-75d3-a69d-74a38baa13f3`

## What is included

- Human Agency Contract and privacy invariants
- Dynamic Situation Model and situation-specific agents/subagents
- Independent execution events with honest provider/fallback attribution
- Critic, uncertainty ledger, and Next Kindest Step
- Living Plan adaptation that preserves explicit boundaries
- Flutter voice-first experience with the NotAlone neon ring
- Deterministic fallback when no model API key is configured
- FastAPI and Flutter tests plus Vercel configuration

## Runtime honesty

GPT-5.6 through Codex contributed to development during Build Week. That is
separate from the application runtime. The hosted runtime target is Groq with
`openai/gpt-oss-120b`; only trace-confirmed execution is labeled live. The app
remains usable in visibly labeled deterministic fallback.

No automatic emergency call, third-party contact, location sharing, or other
external action occurs without explicit human approval.

## How Codex and GPT-5.6 were used

Codex was the engineering collaborator throughout Build Week, not an embedded
user-facing runtime. In the primary build thread, GPT-5.6 helped inspect the
inherited project, separate the Build Week scope, design the typed human
situation and agency models, implement the dynamic agent runtime, harden retries
and fallback attribution, build focused tests, verify the Vercel deployment,
and audit the claims shown to judges.

The human creator retained the product direction, safety boundaries, consent
semantics, privacy rules, accessibility priorities, and final decisions about
what NotAlone should and should not do. The hosted application currently uses
trace-attributed `openai/gpt-oss-120b` through Groq or a clearly labeled
deterministic fallback; it does not claim that GPT-5.6 is the production
runtime.
## Run locally

### Backend

```powershell
cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python -m uvicorn app.main:app --host 127.0.0.1 --port 8001
```

Without an API key the backend intentionally uses deterministic fallback. For
the hosted Groq target, copy `.env.example` to `.env` and configure it locally;
never commit secrets.

### Frontend

```powershell
cd frontend
flutter pub get
flutter run -d web-server --web-hostname 127.0.0.1 --web-port 8080 `
  --dart-define=OBSERVER_API_URL=http://127.0.0.1:8001
```

## Verify

```powershell
cd backend
python -m pytest tests -q

cd ..\frontend
flutter analyze
flutter test
flutter build web `
  --dart-define=OBSERVER_API_URL=https://backend-mu-rose-49.vercel.app
```

## Judge flow

1. Open the public demo or load the demo situation.
2. Confirm **Do not contact anyone** in the Human Agency Contract.
3. Select **Build around me**.
4. Review the single Next Kindest Step.
5. Select **This is too much**.
6. Confirm that the next step becomes smaller and the privacy boundary remains.
7. Expand **How the AI team worked** to inspect execution attribution.

## Roadmap — Permissioned Life Plugins

Future plugins can prepare a trusted-contact handoff, emergency information,
safety-aware map destinations, parked-car memory, journey breadcrumbs,
translation, documents, reminders, and qualified-help handoffs. Every plugin is
off by default, visible when active, time-bounded, exportable, and deletable.
No silent tracking or autonomous external action is part of the roadmap.

Additional implementation and submission evidence is available under `docs/`.


## Detected evidence (automated analysis)

Indexed codebase: 30 recognized source files, 223 KB.
- Dart (language) — detected in the code
- FastAPI (technology) — detected in the code
- HTML (language) — detected in the code
- Python (language) — detected in the code
- Vercel (technology) — claimed on Devpost, not found in the code

## Codebase structure (from repository index)

### Files (40 of 40)

```
.gitignore
backend/.env.example
backend/.gitignore
backend/.vercelignore
backend/api/__init__.py
backend/api/index.py
backend/app/__init__.py
backend/app/build_week/__init__.py
backend/app/build_week/agent_runtime.py
backend/app/build_week/fallback.py
backend/app/build_week/gpt56_client.py
backend/app/build_week/models.py
backend/app/build_week/orchestrator.py
backend/app/build_week/router.py
backend/app/build_week/verification.py
backend/app/main.py
backend/app/settings.py
backend/requirements.txt
backend/tests/test_build_week_dynamic_swarm.py
backend/tests/test_build_week_evaluations.py
backend/tests/test_gpt56_client.py
backend/vercel.json
docs/BUILD_WEEK_CHANGELOG.md
docs/evidence/BUILD_WEEK_BASELINE_2026-07-13.md
docs/OPENAI_BUILD_WEEK_SUBMISSION.md
frontend/analysis_options.yaml
frontend/lib/app.dart
frontend/lib/config/app_config.dart
frontend/lib/data/services/notalone_live_service.dart
frontend/lib/features/build_week/dynamic_human_swarm_screen.dart
frontend/lib/features/swarm/notalone_cinematic_ui.dart
frontend/lib/main.dart
frontend/pubspec.lock
frontend/pubspec.yaml
frontend/test/widget_test.dart
frontend/web/index.html
frontend/web/manifest.json
frontend/web/vercel.json
LICENSE
README.md
```

### Dependencies

- backend/requirements.txt: fastapi@>=0.115.0, httpx@>=0.27.0, pydantic@>=2.9.0, python-dotenv@>=1.0.0, uvicorn[standard]@>=0.32.0

### Recent commits (newest first)

- docs: record primary Codex session
- docs: explain Codex and GPT-5.6 usage
- feat: publish NotAlone Build Week submission

## Key source files (fetched from GitHub, selected and truncated for size)

### docs/OPENAI_BUILD_WEEK_SUBMISSION.md

```markdown
# OpenAI Build Week Submission — NotAlone

## Submission metadata

- **Category:** Apps for Your Life
- **Title:** NotAlone — A Dynamic AI Swarm for Human Situations
- **Tagline:** Your situation. Your boundaries. A plan built around you.
- **Repository:** `https://github.com/rthgit/notalone-openai-build-week`
- **Public demo:** `https://web-nine-wheat-83.vercel.app`
- **YouTube video (<3 min):** add the final public YouTube URL in Devpost
- **License:** MIT
- **Primary Codex `/feedback` Session ID:** `019f5d92-1d08-75d3-a69d-74a38baa13f3`

## Short description

NotAlone turns complex human situations into coordinated action while keeping
the person in control. It creates a Human Agency Contract, models goals, risks,
constraints and uncertainty, designs a temporary team of specialized agents,
and returns one reversible Next Kindest Step plus a transparent action board.

The application runtime is provider-neutral. The current target is Groq with
openai/gpt-oss-120b, with deterministic fallback when no model key is present.
Only trace-confirmed model execution is labeled live; Groq and GPT-OSS are never
presented as GPT-5.6. GPT-5.6 contributed through the Codex development session,
which is a separate development-time claim.

## The problem

Real human situations rarely fit one category. Losing a phone and documents
while abroad can simultaneously involve personal safety, identity, travel,
money, deadlines, family, and incomplete information. Generic assistants often
produce one long answer without showing what is known, assumed, contradictory,
or professionally sensitive.

## The solution

NotAlone creates the organization required by the situation:

1. **Human Agency Contract** — records the person's current capacity, preferred
   support style, privacy limits, trusted support, autonomy level, and right to
   pause, decline, or change direction.
2. **Situation Model** — goals, urgency, risks, constraints, resources, missing
   information, facts, user claims, and assumptions.
3. **Dynamic Swarm Architect** — generates the smallest useful set of agents and
   subagents, their objectives, dependencies, evidence requirements, stop
   conditions, and professional boundaries.
4. **Independent Runtime** — executes each generated agent and subagent through
   separate trace-attributed model requests, with dependency waves, provider-aware concurrency, bounded retry,
   and per-agent fallback.
5. **Critic and Verification** — identifies contradictions and maintains a claim
   ledger separating verified facts, user claims, assumptions, recommendations,
   and unresolved uncertainty.
6. **Next Kindest Step** — leads with one reversible action sized to the
   person's current cognitive and practical capacity.
7. **Living Plan** — `/build-week/adapt` rebuilds the organization after human
   feedback while deterministic invariants preserve explicit boundaries.

## What was built during OpenAI Build Week

The project had a pre-existing NotAlone foundation bef
[truncated — 10835 more characters]
```

### docs/BUILD_WEEK_CHANGELOG.md

```markdown
# OpenAI Build Week Development Record

> **Submission category:** Apps for Your Life  
> **Build Week:** July 13–21, 2026  
> **Project:** NotAlone — A Dynamic AI Swarm for Human Situations  
> **Tagline:** Your situation. Your boundaries. A plan built around you.  
> **Purpose:** distinguish the pre-existing project from work completed during OpenAI Build Week.

## Evidence status at kickoff

| Evidence | Status | Note |
|---|---|---|
| Git repository in `d:\Noesis\notalone_agent_swarm` | **CONFIRMED — initialized 2026-07-13** | The directory was not a Git repository at kickoff. A new repository was initialized after baseline hashes were captured; no commits existed before Build Week. |
| Root open-source license | **CONFIRMED** | MIT License added for the public hackathon repository. |
| Pre-Build Week handoff | **CONFIRMED** | `PROGETTO.md`, last documented snapshot July 13, 2026. |
| Pre-Build Week strategic summary | **CONFIRMED** | `docs/RESOCONTO_HACKATHON.md`, created July 13, 2026. |
| Pre-Build Week automated baseline | **CONFIRMED** | Backend suite reported 142 passing tests on July 13, 2026. |

## Existing before July 13, 2026

The following capabilities are the inherited baseline. They must not be represented as newly built during OpenAI Build Week.

### Product and frontend

- Flutter `NotAloneApp` and live console.
- Human, Operator, and Proof modes.
- Cinematic dark UI and central NotAlone interaction.
- Device channels for phone, glasses, drone, robot, vehicle, and wearable.
- Existing emergency UI and device-context views.
- Existing 4D swarm visualization.
- Pre-rendered cinematic and technical demo videos.

### Backend and orchestration

- FastAPI application and existing router set.
- Unified `/notalone/intake` pipeline.
- Deterministic Situation Autopilot.
- Instant Choice Engine.
- Situation-based worker selection and adaptive swarm scaffolding.
- Human Flow and Next Best Step cards.
- Mission Thread and Proof Mode.
- Safety Gate and bounded automation.
- Emergency layer and context lock.
- Five-tier in-process memory.
- Keyword RAG.
- MCP-ready deterministic tool registry.
- Local deterministic A2A message bus.
- Provider-agnostic model gateway and telemetry.
- Vision pipelines for external OpenAI-compatible providers and local fallbacks.
- Simulated consent-first ecosystem connectors.

### Quality and assets

- 142 passing backend tests at kickoff.
- Flutter static analysis, widget test, and web build previously verified.
- Primary hero video:
  `docs/demo_video/notalone_cinematic_product_film_v2_1_stable.mp4`.
- Existing judge walkthrough, safe claims, architecture, and submission documents.

## Built during OpenAI Build Week

Only completed, tested work should be moved into this section. Planned work remains marked **PLANNED**.

### 1. Dynamic Situation Model — IMPLEMENTED (MVP)

The structured runtime converts an unstructured human situation into a typed model containing:

- goals and desired outcomes;
- urgency and t
[truncated — 12699 more characters]
```

### backend/requirements.txt

```
fastapi>=0.115.0
uvicorn[standard]>=0.32.0
pydantic>=2.9.0
httpx>=0.27.0
python-dotenv>=1.0.0

```

### backend/api/index.py

```python
"""Vercel serverless entry point for the NotAlone FastAPI application."""

from app.main import app

```

### backend/app/main.py

```python
"""Minimal FastAPI entry point for the NotAlone Build Week submission."""

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

from .build_week.router import router as build_week_router


app = FastAPI(
    title="NotAlone Build Week API",
    description="Person-centered dynamic situation swarm with human approval.",
    version="1.0.0",
)

app.add_middleware(
    CORSMiddleware,
    allow_origin_regex=(
        r"^https?://(localhost|127\.0\.0\.1)(:\d+)?$"
        r"|^https://[a-z0-9-]+\.vercel\.app$"
    ),
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

app.include_router(build_week_router)


@app.get("/")
def root() -> dict[str, str]:
    return {
        "status": "ok",
        "app": "NotAlone",
        "health": "/build-week/health",
    }

```

### frontend/pubspec.yaml

```yaml
name: noesis_observer
description: "NotAlone — OpenAI Build Week submission"
publish_to: none
version: 1.0.0+1

environment:
  sdk: ^3.10.1

dependencies:
  flutter:
    sdk: flutter
  http: ^1.2.2
  speech_to_text: ^7.0.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^6.0.0

flutter:
  uses-material-design: true
  assets:
    - assets/logo.png
    - assets/notalone_app_icon.png

```

### frontend/analysis_options.yaml

```yaml
# This file configures the analyzer, which statically analyzes Dart code to
# check for errors, warnings, and lints.
#
# The issues identified by the analyzer are surfaced in the UI of Dart-enabled
# IDEs (https://dart.dev/tools#ides-and-editors). The analyzer can also be
# invoked from the command line by running `flutter analyze`.

# The following line activates a set of recommended lints for Flutter apps,
# packages, and plugins designed to encourage good coding practices.
include: package:flutter_lints/flutter.yaml

linter:
  # The lint rules applied to this project can be customized in the
  # section below to disable rules from the `package:flutter_lints/flutter.yaml`
  # included above or to enable additional rules. A list of all available lints
  # and their documentation is published at https://dart.dev/lints.
  #
  # Instead of disabling a lint rule for the entire project in the
  # section below, it can also be suppressed for a single line of code
  # or a specific dart file by using the `// ignore: name_of_lint` and
  # `// ignore_for_file: name_of_lint` syntax on the line or in the file
  # producing the lint.
  rules:
    # avoid_print: false  # Uncomment to disable the `avoid_print` rule
    # prefer_single_quotes: true  # Uncomment to enable the `prefer_single_quotes` rule

# Additional information about this file can be found at
# https://dart.dev/guides/language/analysis-options

```

### backend/app/__init__.py

```python
"""Noesis Observer backend package (Phase 0 scaffold)."""

```

### frontend/lib/main.dart

```dart
import 'package:flutter/material.dart';

import 'app.dart';

void main() {
  runApp(NotAloneApp());
}

```

### frontend/lib/app.dart

```dart
import 'package:flutter/material.dart';

import 'features/build_week/dynamic_human_swarm_screen.dart';
import 'features/swarm/notalone_cinematic_ui.dart';

class NotAloneApp extends StatelessWidget {
  const NotAloneApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'NotAlone',
      debugShowCheckedModeBanner: false,
      theme: ThemeData(
        brightness: Brightness.dark,
        scaffoldBackgroundColor: NotAlonePalette.deep,
        colorScheme: const ColorScheme.dark(
          primary: NotAlonePalette.violet,
          secondary: NotAlonePalette.cyan,
          surface: NotAlonePalette.deep,
        ),
        useMaterial3: true,
      ),
      home: const DynamicHumanSwarmScreen(),
    );
  }
}

```

[19 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]