Family Assistant

Family Assistant is an LLM-powered application designed for family information management and task automation. It provides multiple interfaces (Telegram, Web UI, Email webhooks) and uses a modular architecture built with Python, FastAPI, and SQLAlchemy. The goal of this project is to create a centralized, intelligent assistant that can help with a variety of tasks, from scheduling and reminders to answering questions based on your personal documents.

The Family Assistant web interface provides easy access to chat, notes, documents, and more

Features

• Multiple Interfaces: Interact with the assistant via Telegram, a responsive web UI, or by forwarding emails.
• LLM-Powered: Leverages the power of Large Language Models for natural language understanding and generation. You can configure different models for different tasks.
• Task Automation: Automate repetitive tasks with a powerful scheduling and callback system.
• Document Indexing: Ingest and search through your documents, including PDFs, text files, and web pages. The assistant can use this information to answer questions.
• Calendar Integration: Connects with CalDAV and iCal calendars to manage your family's schedule.
• Extensible: Add new tools and capabilities to the assistant. The project is designed to be modular and easy to extend.
• Configurable: Fine-tune the assistant's behavior with a flexible configuration system using config.yaml and environment variables.

Key Interface Screenshots

Chat with real-time streaming responses	Organize and manage your notes
Search and manage indexed documents	Create event and schedule-based automations

Architecture

Family Assistant is built with a modern Python stack, featuring:

• Backend: FastAPI for the web server, SQLAlchemy for database interactions, and uv for dependency management.
• Frontend: A React application built with Vite, TypeScript, and Tailwind CSS.
• Asynchronous: Fully asynchronous architecture using asyncio for high performance.
• Dependency Injection: Promotes modular and testable code.
• Repository Pattern: Encapsulates data access logic for clean and maintainable code.
• Event-Driven: Loosely coupled components communicate via events.

For a detailed architecture overview, see docs/architecture-diagram.md.

Getting Started

Prerequisites

• Python 3.10+
• Node.js and npm
• Docker (recommended for the development environment)

Installation

1. Clone the repository:

   git clone https://github.com/your-username/family-assistant.git
   cd family-assistant

   git clone https://github.com/werdnum/family-assistant.git The easiest way to set up your development environment is to use the setup script:

   ./scripts/setup-workspace.sh

   This script will:

   • Create a virtual environment (.venv)
   • Install Python dependencies
   • Install frontend dependencies
   • Set up pre-commit hooks

2. Activate the virtual environment:

   source .venv/bin/activate

For manual installation instructions, see AGENTS.md.

Configuration

The application is configured through config.yaml and environment variables.

• config.yaml: The main configuration file for the application. It defines service profiles, tool configurations, LLM parameters, and the document indexing pipeline.
• prompts.yaml: This file contains the prompts used by the LLM, allowing you to customize the assistant's personality and behavior.
• .env: Create a .env file in the root of the project to store your secrets, such as API keys and database URLs. You can use .env.example as a template.

Environment Variables

The following environment variables are the most important for getting started:

• TELEGRAM_BOT_TOKEN: Your Telegram bot token.
• OPENROUTER_API_KEY: Your OpenRouter API key.
• GEMINI_API_KEY: Your Google Gemini API key.
• DATABASE_URL: The URL for your database (e.g., sqlite+aiosqlite:///family_assistant.db or postgresql+asyncpg://user:password@host/dbname).
• ALLOWED_USER_IDS: A comma-separated list of Telegram user IDs that are allowed to interact with the bot.

For a full list of environment variables, see the Configuration Reference.

Usage

Running the Application

To run the application in development mode with hot-reloading:

poe dev

This will start both the backend and frontend servers. You can access the web UI at http://localhost:5173.

Interactive chat with the assistant showing tool usage and streaming responses

Development Commands

The project uses poethepoet as a task runner. Here are some of the most common commands:

• poe lint: Run the full linting suite.
• poe test: Run the test suite.
• poe format: Format the code.
• poe serve: Run the backend server only.
• poe serve-reload: Run the backend server with auto-reloading.
• poe ui-dev: Run the frontend development server.
• poe ui-build: Build the production frontend assets.

For a full list of commands, see the [tool.poe.tasks] section in pyproject.toml.

Testing

To run the full test suite:

poe test

You can also run specific tests:

pytest tests/functional/test_specific.py

The test suite includes unit tests, functional tests, and integration tests. It uses pytest for the backend and vitest for the frontend.

Frontend Development

The frontend is a React application located in the frontend/ directory. It uses Vite for the build tooling, TypeScript for type safety, and Tailwind CSS for styling.

Frontend Scripts

• npm run dev: Start the Vite development server.
• npm run build: Build the production assets.
• npm run lint: Lint the frontend code.
• npm run test: Run the frontend tests with vitest.
• npm run format: Format the frontend code with biome.

Database Migrations

The project uses Alembic for database migrations.

• Create a new migration:

  When you make changes to the SQLAlchemy models, you'll need to generate a new migration script:

  alembic revision --autogenerate -m "Your migration message"

• Apply migrations:

  To apply the latest migrations to your database:

  alembic upgrade head

Documentation

For Users

• Quick Start Guide - Get started in 5 minutes
• Features Overview - Complete feature catalog
• User Guide - Comprehensive usage documentation
• FAQ - Frequently asked questions
• Scheduling - Reminders and scheduled tasks
• Scripting - Automation with scripts
• Camera Integration - Security camera features
• Browser Automation - Web browsing and automation
• Image Tools - Image generation and editing

For Developers

• AGENTS.md - Development setup and guidelines
• Contributing - How to contribute
• Architecture - System architecture
• Style Guide - Code style and conventions
• API Documentation - REST API reference

For Operators

• Operator Getting Started - Start here for deployment
• Render Deployment - One-click cloud deployment
• Production Deployment - Advanced Kubernetes deployment
• Configuration Reference - All config options
• Monitoring - Logging and observability
• Backup & Recovery - Data protection
• Runbooks - Operational procedures