Development Log

This file contains a log of development sessions, capturing key learnings, architectural insights, and summaries of changes. It is extracted from the more comprehensive GEMINI.md.bak file.

Session Summary (Gemini, 2025-08-16)

This section documents a collaborative development session focused on dependency modernization, new feature integration, and UI/UX refinements.

Project Understanding & Key Learnings

• Primary Goal: The Agora is a Flask-based server for a distributed knowledge graph, designed to connect "digital gardens" into a collaborative, problem-solving commons.
• Tech Stack: The project uses uv for Python dependencies, npm for frontend packages, Jinja2 for templating, and TypeScript (compiled to JS with esbuild) for client-side interactivity.
• Architecture: A key pattern is the filesystem-as-database, where Markdown/text files in user gardens are parsed to build the graph. Configuration is king, with app/config.py acting as the source of truth for feature flags, API keys, and environment URLs.
• Development Workflow:
  1. Install dependencies: uv sync (Python) and npm install (JS).
  2. Run the dev server: ./run-dev.sh.
  3. Crucially: After changing TypeScript files in app/js-src/, they must be re-compiled to JavaScript using npm run build.
  4. Production deployment is managed by a systemd service (agora-server.service) which executes run-prod.sh. A typical deploy involves git pull, uv sync, and systemctl --user restart agora-server.

Summary of Changes Implemented

1. Dependency Modernization: Poetry to uv

• Goal: Remove all traces of the old poetry dependency manager to align with the project’s move to uv.
• Actions:
  • Deleted poetry.lock.
  • Updated README.md with uv installation and usage instructions.
  • Modified entrypoint.sh and Dockerfile to use uv sync instead of poetry install.
  • Confirmed pyproject.toml was already in a compatible format.

2. Feature: Gemini AI Integration

• Goal: Add Google’s Gemini as a second AI provider alongside the existing Mistral implementation, with a clean user interface.
• Actions:
  • Backend:
    • Added GEMINI_API_KEY handling in app/config.py.
    • Added the google-generativeai library to pyproject.toml and installed it.
    • Implemented a gemini_complete function in app/providers.py.
    • Created a new, separate API endpoint /api/gemini_complete/<prompt> in app/agora.py.
  • Frontend:
    • Refactored app/templates/genai.html to use a tabbed interface for selecting between Mistral and Gemini.
    • Updated app/js-src/main.ts to handle tab clicks, fetch from the correct API endpoint, and load the content into a shared div.
    • Ensured the default provider (Mistral) loads automatically when the section is first expanded.
    • Re-added external links for ChatGPT and Claude with a "⬈" symbol to distinguish them.

3. UI/UX Refinements

• "Agora Toggle" Link: Modified the "⸎" link in the footer to be a true toggle. It now reads from config.py to link from the dev environment to production and vice-versa, preserving the user’s context.
• CSS Style Distinction:
  • Refactored the styling for .intro and .info-box divs to create a clearer visual hierarchy for different types of messages.
  • Updated app/templates/sync.html to use the new .intro class for search-related feedback.
  • Adjusted styles in both screen-dark.css and screen-light.css, ensuring the logic was correct for both themes and respected the CSS import order.