FocusSpeak AI

FocusSpeak AI is a personalized language learning project built with a Flutter frontend and a FastAPI backend. The system uses a multi-agent LLM pipeline to support interest-based conversation, grammar feedback, short-term chat memory, graph-based learning memory, and mastery tracking.

Repository Structure

• focus_speak_app/
  Flutter mobile application
• focus-speak-backend/
  FastAPI backend, LangGraph agent flow, Neo4j memory, and offline evaluation scripts

Main Features

• English and Spanish practice
• Interest-based conversation topics
• Tutor / Reviewer / Archiver multi-agent flow
• Grammar correction and memory tracking
• Neo4j-based mastery tracking
• Offline LLM-as-a-Judge evaluation
• Pipeline latency measurement and logging

Technologies Used

• Flutter
• FastAPI
• LangGraph
• Neo4j
• Gemini API
• OpenRouter API

Required Libraries / Services

Backend

The backend currently depends on these Python packages:

• fastapi
• uvicorn
• python-dotenv
• neo4j
• bcrypt
• python-jose
• email-validator
• langgraph
• langchain-google-genai
• openai

You also need:

• a running Neo4j database
• a Gemini API key for the main tutor pipeline
• an OpenRouter API key for the offline judge/evaluation pipeline

Frontend

The frontend uses standard Flutter dependencies from pubspec.yaml.

Environment Variables

Create a .env file inside focus-speak-backend/ with values like:

NEO4J_URI=bolt://127.0.0.1:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password
GEMINI_API_KEY=your_gemini_key
JWT_SECRET=your_secret
OPENROUTER_API_KEY=your_openrouter_key
OPENROUTER_MODEL=openai/gpt-oss-20b:free

How to Run the Project

1. Start the backend

Open a terminal in focus-speak-backend/ and run:

uvicorn main:app --reload --port 8001

The backend will be available at:

http://127.0.0.1:8001

2. Start the Flutter app

Open another terminal in focus_speak_app/ and run:

flutter pub get
flutter run

Running the Offline Evaluation

The offline evaluation script is located here:

focus-speak-backend/eval/judge_runner.py

Validate the dataset only

cd focus-speak-backend
python eval\judge_runner.py

Generate system corrections only

python eval\judge_runner.py --generate-system --limit 3

Run the full judge pipeline

python eval\judge_runner.py --run-judge --limit 3

Evaluation outputs are written to:

focus-speak-backend/eval/results/

Logs and Metrics

Backend latency logs are written to:

• focus-speak-backend/logs/pipeline_metrics.jsonl
• focus-speak-backend/logs/pipeline_metrics_pretty.log
• focus-speak-backend/logs/pipeline_metrics_presentation.json

These logs include:

• total pipeline latency
• per-node latency
• refinement usage
• live news usage

Sample Input / Output

Sample chat request

{
  "mesaj": "Not only he missed the deadline, but he also ignored the client.",
  "dil": "İngilizce",
  "gecmis": []
}

Sample chat response

{
  "kullanici": "Not only he missed the deadline, but he also ignored the client.",
  "tutor_yaniti": "That is an interesting point. In a professional setting, missing a deadline and ignoring a client can seriously damage trust. Why do you think communication is so important in software projects?",
  "hata_var_mi": true,
  "duzeltme": "Not only did he miss the deadline, but he also ignored the client.",
  "hata_kurallari": ["Word Order"]
}

Sample evaluation input

{
  "id": "en_c2_sample",
  "target_language": "İngilizce",
  "student_level": "C2",
  "student_sentence": "Rarely he had seen such a poorly designed system in a production environment.",
  "gold_error_exists": true,
  "gold_error_rules": ["Word Order"],
  "gold_correction": "Rarely had he seen such a poorly designed system in a production environment."
}

Sample evaluation summary output

{
  "sample_count": 10,
  "mean_pedagogical_score": 5.0,
  "mean_overall_score": 4.616
}

Notes

• The main live tutor flow uses Gemini.
• The offline evaluation pipeline uses OpenRouter.