firme-tutor 0.2.0__tar.gz

firme_tutor-0.2.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: firme-tutor
+Version: 0.2.0
+Summary: Socratic AI tutor and typing practice for Firme Coding fellows
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.105.0
+Requires-Dist: fastapi>=0.136.0
+Requires-Dist: uvicorn>=0.48.0
+Requires-Dist: sqlalchemy>=2.0.50
+Requires-Dist: pydantic>=2.13.0
+Requires-Dist: pydantic-settings>=2.14.0
+Requires-Dist: python-dotenv>=1.2.0
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pytest; extra == "dev"

firme_tutor-0.2.0/README.md

@@ -0,0 +1,184 @@
+# Firme Tutor
+
+A Socratic AI tutor and typing practice app for [Firme Coding](https://firmecoding.org) fellows. Built with FastAPI + React, powered by Claude.
+
+## Features
+
+- AI tutor that guides learners with questions (never gives direct answers)
+- Browser-based typing game with reentry-themed content
+- Multi-modal teaching (text, visual, audio, hands-on)
+- Fellow memory — the tutor learns about each person across sessions
+- Progress dashboard for staff and funders
+
+## Quick Start (Local Development)
+
+```bash
+# 1. Clone the repo
+git clone git@gitlab.com:firme-coding/firme-tutor.git
+cd firme-tutor
+
+# 2. Create a virtual environment and install
+python -m venv venv
+source venv/bin/activate    # macOS/Linux
+pip install -e ".[dev]"
+
+# 3. Add your API key
+cp .env.example .env
+# Edit .env and add your ANTHROPIC_API_KEY
+
+# 4. Start the backend
+python -m firme_tutor
+
+# 5. In a separate terminal, start the frontend
+cd firme_tutor/frontend
+npm install
+npm run dev
+```
+
+The app will be at `http://localhost:5173` (frontend) proxying to `http://localhost:8000` (API).
+
+## Adding firme-tutor to Your Project (Step by Step)
+
+### Step 1: Install the package
+
+```bash
+pip install firme-tutor
+```
+
+That's it. Same as installing any other Python package.
+
+### Step 2: Save it to your dependencies
+
+So other people (or your deployment) can install it too.
+
+**If your project uses `requirements.txt`:**
+
+```
+firme-tutor
+```
+
+**If your project uses `pyproject.toml`:**
+
+```toml
+[project]
+dependencies = [
+    "firme-tutor",
+]
+```
+
+### Step 3: Set the API key
+
+The tutor needs an `ANTHROPIC_API_KEY` to talk to Claude. Create a `.env` file in your project:
+
+```bash
+echo "ANTHROPIC_API_KEY=your-key-here" > .env
+```
+
+Make sure `.env` is in your `.gitignore` so the key doesn't get committed.
+
+### Step 4: Use it in your code
+
+**Use just the tutor (for chatting):**
+
+```python
+from firme_tutor import FirmeTutor
+
+tutor = FirmeTutor(topic="What is a variable?")
+reply = tutor.chat("I don't understand what a variable does")
+print(reply)
+```
+
+**Run the full web app (tutor + typing game + progress dashboard):**
+
+```python
+from firme_tutor.web import run_server
+
+run_server()  # Starts at http://localhost:8000
+```
+
+**Or from the command line:**
+
+```bash
+python -m firme_tutor
+```
+
+### Updating to the latest version
+
+```bash
+pip install --upgrade firme-tutor
+```
+
+## Publishing a New Version to PyPI
+
+This is for maintainers — how to release a new version so `pip install firme-tutor` gets the latest code.
+
+### One-time setup
+
+1. Create a free account at https://pypi.org/account/register/
+2. Go to https://pypi.org/manage/account/token/ and create an API token
+3. In GitLab, go to **Settings > CI/CD > Variables** and add:
+   - **Key:** `PYPI_TOKEN`
+   - **Value:** the token from PyPI (starts with `pypi-`)
+   - **Check** "Mask variable"
+
+### Releasing a new version
+
+1. Update the version number in `__init__.py`:
+   ```python
+   __version__ = "0.3.0"
+   ```
+
+2. Commit, tag, and push:
+   ```bash
+   git add .
+   git commit -m "release v0.3.0"
+   git tag v0.3.0
+   git push origin main --tags
+   ```
+
+3. GitLab CI automatically builds and publishes to PyPI. Within a few minutes, anyone can run:
+   ```bash
+   pip install --upgrade firme-tutor
+   ```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `ANTHROPIC_API_KEY` | Yes | Claude API key |
+| `FIRME_HOST` | No | Server host (default: `127.0.0.1`) |
+| `FIRME_PORT` | No | Server port (default: `8000`) |
+| `FIRME_DATABASE_URL` | No | SQLAlchemy DB URL (default: SQLite at `~/.firme-tutor/firme_tutor.db`) |
+| `FIRME_DEBUG` | No | Enable debug mode (default: `false`) |
+
+For local dev, put these in a `.env` file. For deployment, set them in your hosting platform or GitLab CI/CD Variables.
+
+## Deployment
+
+The repo includes a `Dockerfile` and `.gitlab-ci.yml` for CI/CD:
+
+```bash
+# Build the Docker image
+docker build -t firme-tutor .
+
+# Run it (pass the API key at runtime, never bake it into the image)
+docker run -p 8000:8000 -e ANTHROPIC_API_KEY=sk-ant-... firme-tutor
+```
+
+GitLab CI will automatically lint, build the frontend, and push a Docker image to the GitLab Container Registry on pushes to `main`.
+
+## Project Structure
+
+```
+firme_tutor/
+  tutor.py          # FirmeTutor class — one instance per session
+  prompts.py        # System prompts (Socratic persona, insight extraction)
+  curriculum.py     # Module and curriculum content
+  db/               # SQLAlchemy models and engine
+  multimodal/       # Learning mode definitions (text/visual/audio/kinesthetic)
+  typing_game/      # Sentence content, keyboard mapping, scoring
+  web/              # FastAPI app, routers, config
+    routers/        # API endpoints (auth, chat, typing, progress)
+    dist/           # Built React frontend (generated by npm run build)
+  frontend/         # React + TypeScript + Vite source
+```

firme_tutor-0.2.0/__init__.py

@@ -0,0 +1,46 @@
+"""
+firme-tutor
+-----------
+AI-powered Socratic tutor for Firme Coding fellows.
+Built on the Claude API. Designed to guide learners through
+lessons and homework without giving direct answers.
+
+Includes:
+- Socratic AI tutor with multi-modal teaching (text, visual, audio, hands-on)
+- Typing practice game with reentry-themed content
+- Progress tracking API for staff and funders
+- Fellow memory — the tutor remembers each learner across sessions
+
+Basic usage:
+    from firme_tutor import FirmeTutor
+
+    tutor = FirmeTutor(topic="What is a variable?")
+    reply = tutor.chat("I don't understand what a variable does")
+    print(reply)
+
+Run the web app:
+    pip install "firme-tutor[web]"
+    firme-tutor-web
+
+    # or
+    python -m firme_tutor
+"""
+
+from .tutor import FirmeTutor
+from .prompts import build_system_prompt, BASE_SYSTEM_PROMPT
+from .curriculum import MODULES, get_curriculum_for_module
+from .multimodal.modes import LearningMode
+from .typing_game.sentences import STAGES as TYPING_STAGES
+
+__version__ = "0.2.0"
+__author__  = "Maria D. Martinez <maria@firmecoding.org>"
+
+__all__ = [
+    "FirmeTutor",
+    "build_system_prompt",
+    "BASE_SYSTEM_PROMPT",
+    "MODULES",
+    "get_curriculum_for_module",
+    "LearningMode",
+    "TYPING_STAGES",
+]

firme_tutor-0.2.0/__main__.py

@@ -0,0 +1,8 @@
+"""
+Allow running the web server with: python -m firme_tutor
+"""
+
+from firme_tutor.web import run_server
+
+if __name__ == "__main__":
+    run_server()