stephenwzkong/personal_assistant

Purpose and Entry Points

Personal Assistant is a full-stack, domain-oriented assistant for finance, productivity, social, wellness, calendar, tasks, and conversational support. Backend entry points are the API app and runner: src/assistant/api/main.py, src/assistant/runner.py. The browser client starts at src/assistant/frontend/src/main.tsx and composes its application shell in src/assistant/frontend/src/app/App.tsx.

API and Client Boundary

The Python API exposes chat, session, calendar, and task boundaries through src/assistant/api/routes/chat.py, src/assistant/api/routes/session.py, and src/assistant/api/routes/calendar.py. The React/Vite frontend calls these boundaries through stateful hooks—src/assistant/frontend/src/hooks/useChat.ts, src/assistant/frontend/src/hooks/useSession.ts, and src/assistant/frontend/src/hooks/useTasks.ts—rather than embedding backend logic in page components.

Agent Routing and Execution

src/assistant/agents/root_orchestrator.py is the primary control point for interpreting user requests and selecting specialist handling. Domain routers partition multi-agent behavior for productivity, social, and wellness: src/assistant/agents/productivity/productivity_router.py, src/assistant/agents/social/social_router.py, and src/assistant/agents/wellness/wellness_router.py. Specialists then cover discrete concerns such as finance, tasks, fitness, meals, sleep, reading, school, relationships, and news.

Tool and Schema Layer

Agents perform application actions through domain tools, which form the operational boundary to persistence and external capabilities: src/assistant/tools/shared/calendar_tools.py, src/assistant/tools/productivity/task_tools.py, and src/assistant/tools/shared/memory_tools.py. Typed/domain data definitions are centralized under src/assistant/schema/, notably src/assistant/schema/shared_schemas.py, src/assistant/schema/task_schemas.py, and src/assistant/schema/memory_schemas.py. This separates conversational decisions from data operations.

Memory and Cloud Persistence

Conversation/session memory is handled by a dedicated subsystem: src/assistant/memory/service.py, src/assistant/memory/firestore_session_service.py, and src/assistant/memory/cross_domain.py. The repository also includes a BigQuery integration at src/assistant/db/bq_client.py. Google Cloud authentication and project configuration are required; the runtime expects Google credentials plus GOOGLE_API_KEY and GOOGLE_CLOUD_PROJECT.

Prompt, Skill, and Knowledge Assets

Behavior is largely data-driven through versioned prompt and skill documents. The orchestrator prompt is src/assistant/prompts/root_orchestrator.md; reusable prompt assembly is in src/assistant/prompts/loader.py; skill loading is in src/assistant/skills/loader.py. Domain guidance exists as skills and reference material, e.g. src/assistant/skills/finance/SKILL.md and src/assistant/knowledge/wellness/fitness.md, allowing domain behavior to evolve independently of routing code.

Runtime and Delivery Shape

The backend is Python with dependencies declared in pyproject.toml and src/assistant/requirements.txt; it is containerized by src/assistant/Dockerfile. The frontend is a TypeScript React application with Vite configuration in src/assistant/frontend/vite.config.ts. The central end-to-end flow is: UI interaction → API route → root/domain agent routing → tools, memory, and cloud data services → agent response and updated client state.