Skip to content

README.md

Latest commit

 

History

History
274 lines (201 loc) · 7.34 KB

README.md

File metadata and controls

274 lines (201 loc) · 7.34 KB
Raw

Morning Signal

Morning Signal is a source-grounded agent starter kit for turning live web signals into actionable intelligence briefs.

It demonstrates a reusable pattern for production AI agents:

live web signal -> structured evidence -> grounded synthesis -> business action

The included app generates a GTM intelligence brief, but the same architecture can be adapted for competitive intelligence, recruiting signals, market research, pricing monitors, docs-change tracking, financial monitoring, and other workflows where current public web data matters.

Live Demo

The public prototype runs in demo mode, so it does not require live Nimble or OpenAI credentials.

Why This Exists

Most LLM workflows are only as good as the context they receive. If the world changed this morning, a model's memory will not know. Search results alone are also not enough: serious agents need source links, extracted content, metadata, typed outputs, and a repeatable workflow.

Morning Signal shows how to gather evidence before asking the model to reason.

Company URL
  -> human-approved context
  -> LangGraph planner
  -> Nimble Search
  -> Nimble Extract
  -> evidence packet
  -> OpenAI synthesis
  -> inspectable brief

What It Does

The app walks through a four-screen workflow:

  1. Enter a company website.
  2. Generate a company profile, competitors, ICP, and target markets.
  3. Review and approve the research context.
  4. Run an agent that searches, extracts, verifies, and synthesizes a daily brief.

The final brief includes:

  • Today's top prospect signal
  • Industry news in the last 24 hours
  • Competitor moves
  • Nimble's take on the market pattern
  • Three recommended GTM actions
  • Source links for inspection

What Developers Can Learn

  • How to separate retrieval from synthesis
  • How to use human-approved context to improve search quality
  • How to structure evidence before giving it to an LLM
  • How to stream agent progress into a UI
  • How to make demo mode reliable without hiding the production architecture
  • How to adapt one source-grounded agent pattern to multiple domains

Tech Stack

  • Next.js App Router
  • React
  • LangGraph
  • Nimble Search and Extract APIs
  • OpenAI API
  • Zod schemas
  • SQLite for local persistence
  • Resend for optional email delivery
  • Vercel for the public demo

Quickstart

Install dependencies:

npm install

Create a local environment file:

cp .env.example .env

For a safe first run with no external API calls, set:

DEMO_MODE=true

Run the app:

npm run dev -- -p 3001

Open:

http://localhost:3001

Presentation Deck

The Part 1 keynote deck is a static HTML keynote served by the Next app.

Open this exact URL (server must be running):

http://localhost:3001/slides/index.html

Step-by-step:

  1. In this repo, run: npm run dev -- -H 0.0.0.0 -p 3001
  2. Wait until the terminal prints Ready
  3. In your browser open: http://localhost:3001/
  4. Click Open keynote deck → in the top-right
    — or go directly to http://localhost:3001/slides/index.html
  5. Use → / ← to move slides; F for fullscreen

Also available: /deck (redirects to the same file).

Speaker notes and timing: docs/presentation/SPEAKER_NOTES.md
Talk outline: docs/TALK_OUTLINE.md
Demo video path: public/slides/demo.mp4

In demo mode, use:

https://www.nimbleway.com

Demo mode intentionally uses deterministic fixture data. It is designed for public demos, screenshots, and local evaluation without secrets.

Live Mode

To run against real providers, set:

DEMO_MODE=false
NIMBLE_API_KEY=your_nimble_key
OPENAI_API_KEY=your_openai_key

Optional:

NIMBLE_BASE_URL=https://sdk.nimbleway.com/v1
OPENAI_MODEL=gpt-4.1-mini
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=your_langsmith_key
LANGSMITH_PROJECT=nimble-gtm-signal-agent

With live mode enabled, the app can research public HTTP/HTTPS company websites, call Nimble Search and Extract, and synthesize the brief with OpenAI.

Email Delivery

Email delivery is optional and uses Resend.

RESEND_API_KEY=your_resend_key
NEWSLETTER_FROM="Morning Signal <onboarding@resend.dev>"
NEWSLETTER_TO=you@example.com
NEWSLETTER_ALLOWED_RECIPIENTS=you@example.com

The app only sends to the configured allowlist. This keeps demos from becoming an accidental open email relay.

Code Tour

  • app/page.tsx - product UI and agent workflow states
  • app/api/company/route.ts - company profile discovery endpoint
  • app/api/brief/route.ts - non-streaming brief generation endpoint
  • app/api/brief/stream/route.ts - streaming agent progress endpoint
  • lib/agent.ts - LangGraph planning, search, extract, evidence, and synthesis graph
  • lib/nimble.ts - Nimble Search/Extract integration and demo fixtures
  • lib/llm.ts - OpenAI synthesis and structured newsletter generation
  • lib/types.ts - Zod schemas and TypeScript types
  • lib/store.ts - local SQLite persistence
  • lib/email.ts - optional newsletter delivery

Architecture

Read docs/ARCHITECTURE.md for the full system walkthrough.

The short version:

  1. The user gives the agent a company URL.
  2. The system builds a profile and asks the user to approve it.
  3. LangGraph plans research lanes from approved context.
  4. Nimble Search discovers current sources.
  5. Nimble Extract turns pages into usable evidence.
  6. The app assembles a source packet.
  7. OpenAI synthesizes only after the evidence is assembled.
  8. The UI renders an inspectable brief.

Adapting The Agent

Morning Signal is intentionally domain-light. The same pattern can become:

  • A recruiting intelligence agent
  • A competitor pricing monitor
  • A docs-change watcher
  • A market research assistant
  • A financial signal brief
  • A partner/news monitor
  • A local lead-finding workflow

Read docs/ADAPT_THIS_AGENT.md for extension patterns.

Production Notes

Before using this pattern in production, plan for:

  • durable storage instead of local SQLite on serverless platforms
  • retries, backoff, and partial-result handling
  • source scoring and deduplication
  • citation validation
  • per-run cost limits
  • auth and tenant isolation
  • background jobs for long-running crawls
  • observability and evals

Read docs/PRODUCTION_GUIDE.md and docs/EVALUATION.md.

Security

  • Never commit .env or provider secrets.
  • Use demo mode for public deployments.
  • Keep live Nimble/OpenAI keys in local or hosting-provider environment variables.
  • .vercelignore excludes local env files, build caches, local databases, and presentation artifacts from Vercel uploads.
  • Company discovery rejects private/local hostnames.
  • Email sending requires an explicit allowlist.

Read SECURITY.md for more detail.

Useful Commands

npm run typecheck
npm run build
npm audit --omit=dev
npm run dev

Background

This project began as a Nimble Principal Developer Advocate assignment demo. The public version is framed as a reusable reference implementation for developers building source-grounded agents with live web data.