KnowBear

KnowBear is a search-driven AI app that explains any topic in multiple readability levels. It supports two runtime modes:

• fast for low-latency responses
• ensemble for higher-quality synthesis

Both modes use the same retrieval entry point and enrich prompts with live web context before generation.

Features

• Search-driven explanation workflow
• fast mode: quick response path
• ensemble mode: multi-model generation with judge selection
• Streaming responses over SSE
• Export as .txt or .md
• Rate limiting: 5 requests/hour per IP

Architecture (High Level)

• Frontend: React + Vite UI for search, mode selection, streaming, and export
• Backend: FastAPI API for query, stream, export, and health endpoints
• LLM routing layer: provider abstraction for model routing/judging
• LiteLLM proxy: optional external gateway integration point (not bundled in this repo)
• Search API integration: Exa, Tavily, and Serper for retrieval context

API Endpoints

• GET /api/pinned -> curated starter topics
• POST /api/query -> generate one or more levels
• POST /api/query/stream -> stream generated text
• POST /api/export -> export as txt or md
• GET /api/health -> service status

Setup

1) Install dependencies

npm install
pip install -r api/requirements.txt

2) Configure environment

Copy .env.example to .env and set required keys.

Required:

• GROQ_API_KEY
• VITE_API_URL

Recommended:

• GEMINI_API_KEY (judge/fallback path)
• TAVILY_API_KEY
• SERPER_API_KEY
• EXA_API_KEY

3) Run the app

Backend:

python3 -m uvicorn main:app --reload

Frontend:

npm run dev

Usage

1. Open the app at http://localhost:5173/app (or your configured frontend URL).
2. Enter a topic.
3. Choose mode:
   • fast for speed
   • ensemble for stronger quality
4. Read the streamed response and export if needed.

Validation

npm run type-check
npm test -- --run
python3 -m compileall -q api
python3 -c "import main; print(bool(main.app))"