Basis

Problem

Serious public-market researchers revisit the same companies and theses for months or years. Yet every review begins like a restart: reopen the earnings call, compare estimates, check insider activity, reconstruct what mattered last time, and prove where each conclusion came from. The information exists, but the continuity does not.

Generic AI can summarize a prompt, and research platforms can surface more documents. Basis chooses a narrower recurring job: what changed since I last looked, why should I believe it, and did the system learn what matters to my thesis? Fluent answers make the problem worse when they hide the evidence window or make missing data look like no change.

Solution

Basis is an adaptive evidence journal for a user-managed watchlist of supported US-listed companies. It remembers the researcher's last meaningful review, refreshes three bounded evidence lanes—forward-observed analyst estimates, SEC-reported insider purchases, and adjacent-quarter earnings-call language—and prepares a briefing about what materially changed since then.

The experience is one continuous loop:

Check: see what changed since the last review, including an honest no-change result when appropriate. Ask: inspect the source, exact quote, comparison period, confidence basis, and what Basis checked behind every material claim. Teach: mark a finding Important, Irrelevant, or Thesis-changing and watch the next briefing adapt—with an explanation and Undo.

Basis starts from a strict trust promise: a partial answer is acceptable; a silently partial answer is not. Every material claim expands into a receipt containing its source records, effective and comparison periods, confidence basis, derivation path, and exact coverage state. Missing or failed evidence remains visible instead of being presented as “nothing happened.”

Feedback is equally inspectable. Basis stores an immutable feedback event and thesis version, adjusts bounded monitoring priorities, regenerates the briefing, and shows the before/after thesis diff plus a receipted “Because you said” explanation. Ask Basis extends the same evidence contract to on-demand questions: accumulated Firestore evidence comes first, and a private Financial Modeling Prep MCP service fills only material gaps.

Why It Matters

Public-market research is not short on information; it is short on continuity and proof. Basis helps a researcher resume a thesis instead of restarting the research.

That makes the agent useful across time without asking the user to surrender judgment. Basis performs bounded monitoring work in the background, remembers explicit preferences, shows exactly how those preferences changed its behavior, and preserves the evidence needed to disagree with it. It remains research software—not investment advice—and never places trades, builds portfolios, predicts returns, or emits buy/sell recommendations.

Key Features

Resume, do not restart: each briefing answers what changed since the last one the researcher actually viewed. Evidence on every material claim: source identity, exact quotes, dates, comparison periods, confidence basis, derivation, and coverage are inspectable inline. Trust the gaps: loaded, pending, failed, and unavailable evidence remain explicit at both briefing and claim level. Verifiable transcript shifts: adjacent-quarter management-language changes require calibrated semantic retrieval plus exact quote, speaker, role, date, and offset validation. Visible, reversible learning: feedback changes the next briefing through immutable thesis versions, inspectable field diffs, “Because you said” explanations, and Undo. Ask from accumulated context: Ask Basis handles company research, primary-source management language, and dated reported changes without reverting to blank-slate chat or exposing an unrestricted financial toolset. Dynamic watchlist: add, inactivate, restore, refresh, and independently backfill supported NASDAQ, NYSE, AMEX, and CBOE listings while excluding OTC securities. Spoken morning update: an authenticated server-rendered script uses Google Chirp 3 HD (en-US-Chirp3-HD-Kore) only after Listen, reuses a private create-only MP3 cache, and never falls back to browser speech.

How We Used AI

Basis uses Google ADK 2.3 and three Google models through the global Gemini Enterprise Agent Platform endpoint:

Gemini 3.6 Flash performs bounded briefing selection, evidence-constrained thesis updates, and Ask Basis synthesis. It may select only supplied event/receipt pairs or propose changes to an allowed thesis schema. Gemini 3.5 Flash Lite classifies one matched pair of adjacent-quarter transcript chunks at a time into a typed narrative-change candidate. gemini-embedding-001 creates one 768-dimensional, manually normalized semantic-similarity vector per transcript chunk for adjacent-quarter candidate retrieval.

The model boundary is intentionally narrow. Deterministic code owns arithmetic, thresholds, IDs, watchlist membership, anchor selection, coverage, confidence, ranking, monitoring weights, exact quote verification, receipt attachment, and field-level diffs. Invalid structured output or unsupported evidence fails visibly instead of being repaired into a plausible claim.

The separate Ask Basis ADK agent queries Firestore first and can reach only 16 explicitly allowlisted tools on a private self-hosted FMP MCP service. Tool responses are archived before selection and must pass the shared evidence contract before synthesis.

How We Used Codex

Codex was the engineering and verification partner across the project. It helped turn the initial product idea into the ratified scope, PRD, technical specification, and ordered build checklist; implemented executable behavior in RED→GREEN slices; traced shared contracts before changes; reviewed the evolving diff for correctness, security, accessibility, and agent-native behavior; and maintained exact phase evidence.

Codex also ran the production release and formal dogfood loops. Those passes found and closed production-only issues including truncated structured thesis output, incomplete failed-period wording, foreign/OTC search leakage, and non-modal access behavior. The final pass exercised the deployed app, feedback plus Undo, the three Ask Basis archetypes, desktop/mobile keyboard behavior, live source/model contracts, and the private MCP credential boundary.

Architecture

Basis uses one container image for a React/Vite evidence document served by FastAPI on Cloud Run and a Cloud Run Job that performs ingestion. Cloud Scheduler starts weekday refreshes. Firestore is the authoritative domain memory for watchlists, source metadata, normalized events, coverage, briefings, feedback, Ask sessions, and immutable thesis versions. Cloud Storage holds create-only raw source payloads. The private MCP service runs separately on Cloud Run and can be invoked only by the Basis runtime identity. flowchart LR Browser[React evidence document] --> API[FastAPI on Cloud Run] API --> Firestore[(Firestore domain memory)] API --> Job[Cloud Run ingestion job] Scheduler[Cloud Scheduler] --> Job Job --> FMP[FMP REST] Job --> Storage[(Cloud Storage raw archive)] Job --> Gemini[Gemini models through ADK] API --> Ask[Ask Basis ADK agent] Ask --> Firestore Ask --> MCP[Private FMP MCP on Cloud Run] MCP --> FMP

The built-in demo evidence uses sanitized captured FMP responses only at the HTTP transport boundary. The same parsers, qualification engines, persistence, ADK workflows, synthesis, and UI run downstream. Search gaps route through the private MCP service, and newly enrolled symbols may use the hybrid worker's live fallback. Separate live gates cover FMP, Gemini, embeddings, Firestore indexes, Cloud Run, and the credential boundary.

Architecture source: docs/architecture.md Architecture PNG: docs/submission/assets/architecture.png — under 35 MB; the owner form already includes the saved upload.

Technologies And Data Sources

Python 3.12, FastAPI, Pydantic, HTTPX, uv Google ADK 2.3 and Google Gen AI SDK Gemini 3.6 Flash, Gemini 3.5 Flash Lite, gemini-embedding-001 Cloud Run service, Cloud Run Job, Cloud Scheduler, Firestore, Cloud Storage, Secret Manager, Artifact Registry React, Vite, TypeScript, plain CSS, Vitest, Playwright Financial Modeling Prep stable REST APIs and a pinned self-hosted FMP MCP server

Findings And Learnings

Evidence quality and coverage must be separate: a supported claim can still sit inside an incomplete research window. Deterministic code should own qualification truth. Models are most reliable here when they receive small typed evidence sets and cannot invent arithmetic, sources, or coordinates. Structured-output agents need explicit response-budget headroom; schema validation cannot recover JSON truncated by model thinking. Firestore-first retrieval makes accumulated research useful, while a narrowly filtered MCP fallback fills targeted gaps without turning the agent into an unrestricted financial tool caller. User feedback is more credible when the resulting preference, thesis version, ranking change, and explanation all share one immutable provenance chain. Browser platform primitives such as native dialogs provide stronger accessibility behavior with less code than recreating modality in application JavaScript.

Verification And Production Readiness

The evidence-eligibility fix is deployed as commit d265dad1b7b6a546566d5422a7b1632d088541bd on Cloud Run revision basis-00038-92l. The exact approved public demo is v13 at https://youtu.be/Aj40vpNIYLM (public), 3:46, SHA-256 e27296a692e25a10954161512ce787faa7ab242437338b83ae4ef0b26e16bd12. Exact-file visuals, story, and audio approval passed; signed-out checks returned HTTP 200 and playability status OK.

Current clean-default make verify — passed: 609 Python tests, 86 Vitest tests, 66 Playwright checks, 10 fixture/calibration contracts, and 5 Firestore-emulator tests, plus Ruff, Pyright, secret scan, the Phase 6 contract, and the production web build. Current local make verify-handoff — passed after rebuilding the served bundle and refreshing three reviewed screenshots plus source/browser/bundle manifest. Current local make verify-demo — passed for the exact 225.040-second v13 candidate and reports human_approval=approved and publication_status=published. Recorded live, deployed, Phase 6, and formal dogfood evidence remains in docs/phase-reports/ and docs/dogfood-reports/2026-08-23-codex-basis-build-dogfood.md.

Testing Instructions

Hosted demo

Open https://basis-7heosdtitq-uc.a.run.app/. Public briefing and watchlist reads do not require credentials. Expand the briefing coverage basis and any material claim receipt to inspect sources, comparison periods, confidence, derivation, and exact coverage. The public demo video shows the protected feedback, regenerated-briefing, provenance-receipt, Ask, and Undo flow. Protected mutations require Demo access; credentials are intentionally absent from the public project, repository, video, and screenshots.

Local reproduction

Requirements: Python 3.12, uv, Node 22, and pnpm 10. cp .env.example .env make install make verify make verify-phase6-local make verify-handoff

Fixture mode requires no FMP key and diverges from live mode only at the HTTP transport. Cloud/live verification commands require authenticated Google Cloud access and are documented separately in the repository.

make verify-demo is a release-workstation gate. It additionally requires the exact ignored candidate and every hash-bound source named in docs/submission/demo-release.json; those private media artifacts are intentionally absent from a fresh clone.

Public Demo Link

https://basis-7heosdtitq-uc.a.run.app/

Public Repository Link

https://github.com/zaeem-rafiq/Basis — private, as allowed by the event requirements. Devpost reviewer access is active; the Google hackathon reviewer invitation is pending acceptance. The deployed evidence-eligibility work is integrated into the repository's actual default branch through merge commit 63ae5f8.

Demo Video

The exact approved public v13 demo is https://youtu.be/Aj40vpNIYLM. It runs 3:46 and has SHA-256 e27296a692e25a10954161512ce787faa7ab242437338b83ae4ef0b26e16bd12.

0:00–0:17 — user, problem, and purpose: Basis identifies serious public-market researchers, their fragmented recurring evidence workflow, and the Check → Ask → Teach outcome. 0:17–0:30 — live Cloud proof: a redacted read-only projection shows the ready Cloud Run service, current revision at 100% traffic, live URL, and latest completed ingestion Job. 0:30–0:49 — autonomous utility: the deployed watchlist exposes loaded, pending, failed, and unavailable evidence instead of hiding missing data. 0:50–1:24 — Check: a visible interaction opens the source, comparison, confidence, register, and coverage behind a real TSM finding. 1:25–2:08 — Ask: a visible Ask action produces a live answer, then another interaction opens sentence-level proof. 2:10–3:13 — Teach: visible interactions apply Thesis-changing, reveal the exact diff, regenerate a briefing with Because you said provenance, open and close its masked learning receipt, and show the restoring diff after Undo. 3:13–3:45 — architecture and outcome: staged highlights show why Google Cloud, ADK, Gemini, Firestore, Cloud Storage, and the bounded private MCP service are essential, then close on the restored journal.

The v13 edit uses only the reviewed continuous deployed source for product interactions, with disclosed spatially static crops, trims, designed cards, narration, music, and chimes. The access surface is never opened. No credential, account identity, billing detail, private feedback identifier, or secret value appears. No browser response is mocked.

Screenshot Shot List

Ready: morning briefing with the expanded VRT quote-level receipt, comparison period, confidence, and coverage — docs/submission/assets/briefing-light.png. Ready: Ask Basis with a sentence-level company-profile receipt and explicit coverage — docs/submission/assets/ask-basis-light.png. Ready: deterministic browser-contract capture of the regenerated briefing, thesis diff, and expanded learning receipt — docs/submission/assets/feedback-learning-adapted.png. Label it as browser-contract proof in the gallery caption.

Known Limitations

Estimate revisions are forward-observed same-period changes; Basis does not claim historical consensus snapshots unavailable from the source. The app backfills and refreshes user-selected companies rather than continuously ingesting a market universe. Ask Basis is intentionally serialized per app instance and non-streaming so each MCP transport closes cleanly; broader throughput is not claimed. Spoken audio uses the selected en-US-Chirp3-HD-Kore voice through authenticated server-side synthesis. A first uncached Listen may take longer than a cache hit; failures leave the written briefing intact. The dedicated project has two identical $25 budget-alert records from initial bootstrap. This can duplicate notifications but does not create additional spend. The code repository is private; Devpost reviewer access is active and the Google hackathon reviewer invitation is pending acceptance.