How ahmed-ali-313/hackathon-i-physical-ai-humanoid-robotics-textbook works
AI-Native Textbook combines chapter reading with contextual RAG assistance, Urdu translation, and personalized accounts. A learner reads the textbook, can select a passage or ask a question, and receives an attributed response; translation and account preferences form parallel learning-support workflows. The backend also handles conversation persistence and semantic retrieval. The README documents major integrations and capabilities, but several route and service implementations were not sampled, so uncertain internal calls are omitted.
Main entry points: main.py API application · agent_service.py RAG agent · chat.py Chat endpoints · database.py Application database
Components 31
Textbook experience
- Textbook site
textbook/src/theme/Root.tsx - Chat panel
textbook/src/components/ChatPanel/index.tsx - Passage selection
textbook/src/hooks/useTextSelection.ts - Translation control
textbook/src/components/TranslationControl/index.tsx - Profile settings
textbook/src/pages/profile.tsx
Frontend workflows
- Chat workflow
textbook/src/hooks/useChat.ts - Chat client
textbook/src/services/chatApi.ts - Translation workflow
textbook/src/hooks/useTranslation.ts - Translation client
textbook/src/services/translationApi.ts - Authentication UI
textbook/src/contexts/AuthContext.tsx - Preferences client
textbook/src/services/personalizationApi.ts
Backend API
- API application
backend/src/main.py - Chat endpoints
backend/src/api/chat.py - Content endpoints
backend/src/api/content.py - Translation endpoints
backend/src/api/translation.py - Auth endpoints
backend/src/api/auth.py - Preference endpoints
backend/src/api/preferences.py - Authentication service
backend/src/services/auth_service.py
AI services
- Chat service
backend/src/services/chat_service.py - RAG agent
backend/src/services/agent_service.py - Vector search tool
backend/src/tools/vector_search_tool.py - Context formatting
backend/src/tools/retrieve_context_tool.py - Embedding service
backend/src/services/embedding_service.py - Translation service
backend/src/services/translation_service.py
Data and integrations
- Application database
backend/src/database.py - Chat records
backend/src/models/conversation.py - User records
backend/src/models/user.py - Translation cache
backend/src/services/translation_cache_service.py - Qdrant vectors
- OpenAI API
Other components
- Learner
Connections 38
- Learner → Textbook site: reads chapters
- Learner → Chat panel: asks questions
- Textbook site → Passage selection: captures passage
- Passage selection → Chat workflow: supplies selection
- Chat panel → Chat workflow: manages chat
- Chat workflow → Chat client: requests chat data
- Chat client → Chat endpoints: calls chat API
- API application → Chat endpoints: registers router
- API application → Translation endpoints: registers routers
- API application → Auth endpoints: registers routers
- API application → Preference endpoints: registers routers
- API application → Content endpoints: registers routers
- Chat endpoints → Chat service: handles chat
- Chat service → RAG agent: orchestrates responses
- RAG agent → Vector search tool: searches chunks
- RAG agent → Context formatting: formats results
- Vector search tool → Qdrant vectors: searches vectors
- RAG agent → OpenAI API: generates answers
- Embedding service → OpenAI API: creates embeddings
- Context formatting → Chat service: formats sources
- Chat endpoints → Chat records: persists conversations
- Chat records → Application database: stores records
- Learner → Translation control: requests translation
- Translation control → Translation workflow: toggles language
- Translation workflow → Translation client: requests chapter
- Translation client → Translation endpoints: calls translation API
- Translation endpoints → Translation service: translates chapters
- Translation service → Translation cache: checks translation
- Translation cache → Application database: stores translations
- Learner → Profile settings: manages account
- Profile settings → Authentication UI: uses account state
- Authentication UI → Auth endpoints: authenticates
- Auth endpoints → Authentication service: verifies credentials
- Authentication service → User records: loads user
- User records → Application database: stores account
- Profile settings → Preferences client: updates preferences
- Preferences client → Preference endpoints: calls preferences API
- Preference endpoints → Application database: persists preferences