openspec/project.md

Project Context

Purpose

Build an "Accelerated Book Copilot" Streamlit app that ingests long-form content, delivers layered summaries, enables adjustable-speed listening, answers reader questions with cited passages, and enriches context via targeted web crawling.

Tech Stack

• Python 3.11+
• Streamlit for the interactive UI
• LangChain for orchestration, retrieval, and tool management
• Azure OpenAI / OpenAI models for summarization and Q&A
• SentenceTransformers or text-embedding-3-small embeddings
• FAISS (local) or Pinecone (managed) vector store
• TTS utilities from FOMO project (gTTS / local models) with optional Azure Speech
• Newspaper3k / Requests / BeautifulSoup for focused crawling
• Altair for visualization (timeline, reading metrics)

Project Conventions

Code Style

• Pythonic style with type hints, descriptive snake_case naming, and minimal inline comments.
• Prefer pure functions where practical; separate UI logic from data/LLM orchestration.
• Use black/ruff compatible formatting (4-space indent, double quotes acceptable but prefer single quotes unless escaping).
• Avoid interactive input(); rely on Streamlit widgets and session state.

Architecture Patterns

• Layered architecture: ingestion → processing (chunk/embedding/summarization) → experience (UI tabs).
• Retrieval-Augmented Generation for Q&A with citation packaging.
• Background task pattern for heavy preprocessing (async threads or queued jobs).
• Modular service helpers (ingestion, summarization, retrieval, TTS) to keep Streamlit pages thin.

Testing Strategy

• Unit tests for ingestion utilities, chunking, and summarization prompt builders.
• Integration smoke tests for the Streamlit app using sample documents.
• Mock external APIs (Azure OpenAI, Pinecone) to keep CI deterministic.
• Manual regression checklist for multilingual TTS and crawl workflows before demos.

Git Workflow

• Use feature branches named feature/<topic> or fix/<topic> off main.
• Conventional commit messages (e.g., feat: add crawl summarizer) with co-author trailer when pair hacking.
• Pull requests require reviewer sign-off plus local smoke test evidence.
• Avoid committing secrets; rely on .env templates and local dotenv loading.

Domain Context

• Focused on long-form content acceleration for readers, researchers, and students.
• Supports multiple summary granularities (flash, detailed, character/plot focused).
• Q&A must cite source passages to maintain trust; responses should match question language when possible.
• Listening mode ties TTS playback to highlighted text segments for faster comprehension.
• Crawl mode gathers external commentary (reviews, interviews, scholarly notes) to enrich understanding.

Important Constraints

• Must operate within hackathon time constraints; prioritize features that demo well within 3 days.
• Respect licensing of ingested books; app assumes user-provided content is permitted.
• Ensure OpenAI/Azure usage stays within provided quota; implement caching to minimize token spend.
• Crawling restricted to whitelisted, publicly accessible sources to avoid legal issues.
• Offline-friendly fallback path (local embeddings/FAISS) required if Pinecone credentials unavailable.

External Dependencies

• Azure OpenAI / OpenAI API keys for LLM and embedding calls.
• Pinecone account (optional) for managed vector storage.
• Hugging Face / SentenceTransformers models for local embeddings.
• Third-party TTS backends (gTTS/local models/Azure Speech) for audio output.
• Newspaper3k/Requests for external article retrieval; BeautifulSoup for parsing.