Skip to content

README.md

Latest commit

 

History

History
90 lines (68 loc) · 2.86 KB

README.md

File metadata and controls

90 lines (68 loc) · 2.86 KB

GainesAI Thin Slice

A lean AI web app using FastAPI, structured with BFF and Observer patterns. Powered by Amazon Bedrock (Claude Haiku 4.5) via the Converse API.

What it does

Paste rough notes → get back a summary, action items, and a next step.

Architecture

See ARCHITECTURE.md for full Mermaid diagrams.

Browser UI → FastAPI BFF → Agent Service → Bedrock (Converse API) → Structured JSON → UI
  • BFF layer — validates input, delegates to agent service, shapes response for the frontend
  • Agent service — orchestrates prompt → model → parse pipeline, emits observer events
  • Observer — decoupled event system for logging, tracing, telemetry
  • Model layer — Bedrock Converse API, model-agnostic (swappable)
  • Response parser — extracts JSON from model output (handles markdown fences, preamble)

Project structure

app/
  main.py                    # FastAPI entrypoint
  routes/
    analyze.py               # BFF — request handling
  services/
    agent_service.py          # orchestration + observer events
    ai_client.py              # model integration (Bedrock Converse API)
    prompt_builder.py         # prompt construction
    response_parser.py        # raw text → structured output
    observer.py               # event emitter/listener system
  models/
    schemas.py                # Pydantic request/response models
  static/
    index.html / app.js / styles.css
tests/
  test_parser.py

Quick start

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

Create .env in the project root:

DEMO_MODE=true
AWS_REGION=us-east-1
MODEL_ID=global.anthropic.claude-haiku-4-5-20251001-v1:0

Run:

./start.sh
# Open http://127.0.0.1:8000

Modes

Mode Config Behavior
Demo DEMO_MODE=true (default) Returns mock structured output
Live DEMO_MODE=false Calls Bedrock via Converse API

Live mode requires AWS credentials with Bedrock access. The default model is the Claude Haiku 4.5 global inference profile — set AWS_REGION to a supported source region (us-east-1, us-west-2, etc.).

Change isolation

Want to... Change only...
Swap the model ai_client.py
Change the prompt prompt_builder.py
Add logging/tracing Register an observer
Add a mobile frontend New BFF route
Add tool calls or multi-step agent_service.py
Change the response shape response_parser.py

Docs

  • ARCHITECTURE.md — Mermaid component + sequence diagrams
  • WALKTHROUGH.md — Full code walkthrough: BFF pattern, Observer pattern, Converse API, JSON extraction