{"id":32786770,"url":"https://github.com/aldrees7/language-companion","last_synced_at":"2026-05-05T04:36:30.224Z","repository":{"id":322131644,"uuid":"1088286925","full_name":"Aldrees7/language-companion","owner":"Aldrees7","description":"Streamlit-based AI Language Tutor — explain grammar, translate text, generate quizzes, and run SRS reviews with memory persistence. Built with OpenAI + Python.","archived":false,"fork":false,"pushed_at":"2025-11-02T18:00:14.000Z","size":18,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-02T20:11:32.407Z","etag":null,"topics":["ai","education","langchain","language-learning","nlp","openai","python","srs","streamlit","tutor"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Aldrees7.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-02T17:18:37.000Z","updated_at":"2025-11-02T18:24:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Aldrees7/language-companion","commit_stats":null,"previous_names":["aldrees7/language-companion"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Aldrees7/language-companion","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aldrees7%2Flanguage-companion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aldrees7%2Flanguage-companion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aldrees7%2Flanguage-companion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aldrees7%2Flanguage-companion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Aldrees7","download_url":"https://codeload.github.com/Aldrees7/language-companion/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aldrees7%2Flanguage-companion/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":282762578,"owners_count":26723111,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-05T02:00:05.946Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","education","langchain","language-learning","nlp","openai","python","srs","streamlit","tutor"],"created_at":"2025-11-05T05:01:35.452Z","updated_at":"2025-11-05T05:03:06.448Z","avatar_url":"https://github.com/Aldrees7.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧑‍🏫 Language Companion\n**An AI-powered study partner for language learners.**\nPaste any lesson or upload files to explain, translate, analyze grammar, generate quizzes, extract vocabulary, and build review notes with spaced-repetition tracking.\n\n---\n\n## 🚀 Quick Start\n\n### 1️⃣ Install dependencies\n```bash\nuv venv\nuv sync\n```\n\n### 2️⃣ Set your API key\n```bash\n# PowerShell\n$env:OPENAI_API_KEY=\"sk-...\"\n# or Linux/Mac\nexport OPENAI_API_KEY=\"sk-...\"\n```\n\n### 3️⃣ Launch the app\n```bash\nuv run streamlit run src/app/app.py\n```\n\n---\n\n## ✨ Features\n\n### 🧩 Core Modes\n| Mode | Description |\n|-------|--------------|\n| **Explain** | Simplifies and paraphrases text for A2/B1 learners. |\n| **Translate** | Produces a natural, fluent English translation. |\n| **Grammar** | Highlights key grammar points and examples. |\n| **Quiz** | Generates 10 mixed question types (MCQ, cloze, meaning). |\n| **Vocab** | Extracts 10–12 key words/phrases with examples. |\n\n---\n\n### 🧾 Review Note Formats\n| Format | Output Style | Use Case |\n|---------|---------------|----------|\n| **Study Sheet** | Structured sections (TL;DR, Grammar, Vocab, Drills). | Print-style learning notes. |\n| **Flashcards** | `Q:` / `A:` pairs. | Self-testing or Anki import. |\n| **Compact** | 1-line bullets for quick review. | Mobile or smartwatch notes. |\n\n---\n\n### 💾 Spaced Repetition System (SRS)\n- Vocabulary cards saved locally in `src/data/srs_db.json`.\n- Grading buttons adjust review schedule:\n  - **Again:** soon (reset)\n  - **Hard:** shorter delay\n  - **Good:** normal delay\n  - **Easy:** longer delay\n- Persistent storage — all progress is saved between sessions.\n\n---\n\n### 📂 File Support\nSupports `.txt`, `.md`, `.pdf`, and `.docx` uploads.\nAutomatically extracts text using **PyMuPDF** (for PDFs) and **python-docx** (for Word files).\n\n---\n\n## 🧠 Architecture Overview\n\n```\nsrc/\n ├─ app/\n │   └─ app.py              # Streamlit UI\n ├─ agent_core/\n │   ├─ agent.py            # LangChain logic and prompts\n │   └─ prompts/system.json # Base system prompt\n ├─ utils/\n │   ├─ constants.py        # Configuration values\n │   ├─ storage.py          # Local JSON persistence\n │   └─ srs.py              # Spaced repetition scheduler\n └─ data/\n     └─ srs_db.json         # Local SRS deck\n```\n\n---\n\n## 🧩 Tech Stack\n| Component | Library |\n|------------|----------|\n| **Frontend** | Streamlit |\n| **LLM / Agents** | LangChain + OpenAI (GPT-4o-mini) |\n| **Data Handling** | JSON (local storage) |\n| **PDF \u0026 Word Parsing** | PyMuPDF, python-docx |\n| **Code Quality** | Ruff + Black |\n| **Dependency Management** | uv |\n\n---\n\n## 🔧 Constants \u0026 Config\nAll static configuration lives in `src/utils/constants.py` — including:\n- model (`OPENAI_MODEL`)\n- SRS intervals\n- review batch size\n- upload limits\n- paths for data and review notes\n\n---\n\n## 🧪 Example Usage\nUpload a file or paste text such as:\n\n```\nAnna steht früh auf und geht in das kleine Café an der Ecke.\nSie bestellt einen Kaffee mit Milch und ein Brötchen mit Marmelade.\n```\n\nThen choose:\n- Mode → **Explain**\n- Review Note Format → **Study Sheet**\n- Click **Analyze** or **📝 Make Review Note**\n\n---\n\n## 📘 Project Status\n✅ Functional \u0026 stable prototype.\n💡 Optional future upgrades:\n- Deck statistics in sidebar.\n- Lesson history viewer.\n- Cloud sync for user data.\n\n---\n\n## ⚖️ License\nMIT License © 2025 Language Companion Developers\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faldrees7%2Flanguage-companion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faldrees7%2Flanguage-companion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faldrees7%2Flanguage-companion/lists"}