Disclaimer: This is an automated translation. The original documentation is in Russian.

---

Live-Context AI Chat — Developer Guide

Live-Context AI Chat is a desktop MVP application for interactive interaction with cloud LLMs (Google Gemini API) and local models via an OpenAI-compatible API (Ollama, vLLM, LM Studio).

The project is designed to provide neural networks with direct access to the developer's file system ("live context"), automatic file patching (Multi-Canvas), and fine-grained control over token usage.

---

🚀 Key Architectural Features

1. Live File Context:
   • The ContextBuilder service asynchronously reads the current state of tracked files and directories from the disk before each request.
   • The model always sees the freshest edits without the user needing to re-paste code manually.
2. Managed History Depth and Pinning:
   • Context separation into a sliding window (the last $N$ messages) and pinned context (system prompt, tracked files, pinned 📌 messages).
   • Prevents important information from being washed out of the model's memory.
3. Multi-Canvas Auto-Patching:
   • Formatting model responses into structured JSON with diffs (old_code / new_code).
   • The /api/chat/canvas-patch endpoint automatically calculates indent shifts (Smart Indent Adjustment) and applies edits directly to files on disk.
4. FS-XML v1.2 Specification and Execution:
   • Support for file operation markup (<fs_create>, <fs_edit>, <fs_search>, <fs_replace>).
   • A ready-made foundation for parsing and safely executing agentic commands directly from Markdown output.
5. Secure Secret Storage:
   • Encryption of API keys using the AES-Fernet algorithm tied to the operating system's native keystore (keyring / DPAPI / Secret Service).

---

🛠️ Technology Stack

Backend

• Language / Framework: Python 3.13+, FastAPI, Uvicorn (ASGI).
• Database: SQLite + SQLAlchemy 2.0 (Async driver: aiosqlite).
• LLM SDKs:
  • google-genai — official up-to-date SDK for Google Gemini and Gemma 4.
  • openai (AsyncOpenAI) — for OpenAI-compatible local and cloud endpoints.
• Tools: tiktoken (cl100k_base token counting), cryptography + keyring (encryption), aiofiles (asynchronous file reading).

Frontend

• Framework: Vue 3 (Composition API, <script setup>).
• Bundler: Vite.
• State Management: Pinia (modular stores for workspaces, chat, settings, theme, logs, and localization).
• Styling: Tailwind CSS, Catppuccin-like custom variables, Glassmorphism effects.
• Rendering: markdown-it, highlight.js (syntax highlighting), lucide-vue-next (icons).

---

📁 Project Structure

live-context-ai-chat/
├── run.py                 # Main script for parallel launch of FastAPI uvicorn + Vite dev
├── run.bat                # Windows launcher for quick start with .venv activation
├── README.md              # Developer documentation
├── README_USER.md         # User documentation (for exe build)
│
├── backend/               # Server side (FastAPI)
│   ├── main.py            # FastAPI entry point, DB initialization, and CORS
│   ├── requirements.txt   # Python dependencies
│   └── app/
│       ├── api/           # REST & SSE routers
│       │   ├── chat.py       # Response streaming (SSE), generation cancellation, canvas-patch
│       │   ├── files.py      # FS scanning (/ls), temporary file upload
│       │   ├── logs.py       # Retrieval and clearing of system logs
│       │   ├── messages.py   # Message CRUD, pagination, pinned messages
│       │   ├── search.py     # Global full-text search
│       │   ├── theme.py      # Custom theme settings and background upload
│       │   ├── tokens.py     # Precise token calculation via tiktoken
│       │   └── workspaces.py # Workspace CRUD and cloning
│       │
│       ├── core/          # Configuration and security
│       │   ├── config.py     # BaseSettings configuration, DB and folder paths
│       │   ├── constants.py  # Model lists, providers, roles
│       │   ├── security.py   # SystemEncryptionManager (Fernet + keyring)
│       │   └── exceptions.py # Custom exceptions
│       │
│       ├── db/            # Database
│       │   ├── base_class.py # SQLAlchemy Declarative Base
│       │   └── session.py    # AsyncEngine and aiosqlite sessions
│       │
│       ├── models/        # SQLAlchemy models
│       │   ├── workspace.py # Project model
│       │   ├── message.py   # Message model (including JSON fields canvas_data, files)
│       │   └── log.py       # System logs
│       │
│       ├── providers/     # LLM integrations
│       │   ├── factory.py         # Provider factory
│       │   ├── base_provider.py   # Abstract base class
│       │   ├── gemini_provider.py # Google GenAI integration
│       │   └── openai_provider.py # OpenAI/Ollama API integration
│       │
│       ├── repositories/  # Asynchronous Data Access Layer (DAL)
│       │   ├── workspace_repo.py # Key encryption logic, cloning, search
│       │   ├── log_repo.py       # Log rotation and recording
│       │   └── base_repo.py      # Base CRUD repository
│       │
│       └── services/      # Business logic
│           ├── context_builder.py # Assembly of final prompt and history filtering
│           ├── file_service.py    # Recursive file reading from disk
│           └── token_service.py   # Request weight calculation
│
└── frontend/              # Client side (Vue 3 + Vite)
    ├── index.html         # HTML template
    └── src/
        ├── App.vue        # Root layout component
        ├── main.js        # Vue + Pinia entry point
        ├── api/           # Axios client and API modules
        ├── assets/        # CSS (Tailwind, themes, syntax)
        ├── components/    # UI components
        │   ├── chat/      # Chat: Header, InputArea, MessageItem, MessageList, PinnedDrawer, TokenEstimator
        │   ├── common/    # Modals: Delete, Rename, ThemeConfig, DocsModal
        │   ├── settings/  # Settings panel: ApiSettings, ContextSettings, FileExplorerModal, ModelParameters
        │   └── workspace/ # Sidebar: GlobalSearch, WorkspaceItem, WorkspaceList, ErrorLogPanel
        ├── composables/   # Reusable Vue composables (useChatStream, useClipboard, useDragDrop, etc.)
        ├── locales/       # Localization (ru.js, en.js)
        ├── stores/        # Pinia stores (workspaceStore, chatStore, settingsStore, themeStore, etc.)
        └── utils/         # Utilities (markdown parser, token heuristics)

---

⚡ Deployment and Running for Development

1. Requirements

• Python 3.13+
• Node.js 18+ & npm

2. Dependency Installation

Backend:

cd backend
python -m venv .venv
# On Windows: .venv\Scripts\activate
# On Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt

Frontend:

cd frontend
npm install

3. Running the Application

From the project root, run:

python run.py

The script will automatically launch FastAPI at http://localhost:8000 and Vite Dev Server at http://localhost:5173.

---

📄 File Management Protocol Specification (FS-XML v1.2)

The model can return instructions for modifying source code in the form of XML blocks, which are parsed by the client side for subsequent application.

1. File Creation (<fs_create>)

<fs_create path="relative/path/to/file.py">
def main():
    print("Hello World")
</fs_create>

2. File Editing (<fs_edit>)

Option A: Targeted Replacement (Search & Replace)

<fs_edit path="relative/path/to/file.py">
<fs_search>
def main():
    print("Hello World")
</fs_search>
<fs_replace>
def main():
    print("Hello Live Context")
</fs_replace>
</fs_edit>

Option B: Complete File Overwrite

<fs_edit path="relative/path/to/file.py">
<fs_search><all /></fs_search>
<fs_replace>
# Completely new file code
</fs_replace>
</fs_edit>

Note: The system prompt specification for FS-XML v1.2 is located in the folder of this project.