Version 1.0

2026-07-21 22:24:25 +00:00
parent f3645fbfbc
commit 9edbfd3f77
4134 changed files with 1448752 additions and 1 deletions
@@ -1,3 +1,133 @@
 # TactiTerm

-Tactile Terminal: A WebUI/TUI built to help teach and and study programming concepts in an interactive way.
+**Tactile Terminal:** A WebUI / TUI built to help teach and study programming concepts in an interactive, hands-on way.
+
+---
+
+## 🌟 Overview
+
+**TactiTerm** is an interactive software engineering tutor designed with a "guidance over answers" philosophy. Rather than providing copy-paste solutions, TactiTerm uses a **Socratic AI Mentor** to ask probing questions, provide hints, and guide users toward mastering concepts across 10 programming languages.
+
+TactiTerm features both a rich **Terminal User Interface (TUI)** for command-line productivity and a modern **Web UI** featuring the Monaco Editor.
+
+---
+
+## ✨ Features
+
+- 🧠 **Socratic AI Mentor:** Provides step-by-step guidance, code review, and conceptual hints without spoiling direct answers.
+- 💻 **Dual Interfaces:**
+  - **TUI:** Built with Python and Textual for high-productivity, keyboard-driven terminal workflows.
+  - **Web UI:** Built with React, Vite, TypeScript, Tailwind CSS, and Monaco Editor.
+- 🌐 **10 Supported Languages:** Python, C#, C++, Java, JavaScript, TypeScript, Rust, Lua, HTML, and Go.
+- ⚡ **Real-time Linting & Execution:** Tree-sitter powered syntax validation and safe local code execution.
+- 📚 **Interactive Syntax Handbook:** W3Schools-style reference catalog with on-demand AI code examples for functions and core language topics.
+- 🪄 **AI Challenge Generator (GenTUI):** Create and save custom Markdown programming challenges tailored to specific subjects and difficulties.
+- ⚙️ **Configurable & Network Ready:** Easily configure LLM endpoints, ports, and enable `"public": true` to host the Web UI across your local network (`0.0.0.0`).
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Python 3.10+
+- [`uv`](https://github.com/astral-sh/uv) (Python package runner)
+- Node.js & npm (for Web UI)
+- [Devbox](https://www.jetify.com/devbox) (optional, for reproducible envs)
+
+### Installation
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/your-username/TactiTerm.git
+   cd TactiTerm
+   ```
+
+2. Install dependencies:
+   ```bash
+   make install
+   ```
+
+---
+
+## 🎮 Usage
+
+### Terminal Interface (TUI)
+
+Launch the interactive terminal application:
+```bash
+make tui
+```
+
+Additional TUI modes:
+- `make gentui` - Launch the standalone GenTUI AI Challenge Generator.
+- `make tui-debug` - Launch TUI in debug logging mode.
+
+### Web Interface (Web UI)
+
+Launch the FastAPI backend server and Vite frontend dev server:
+```bash
+make web
+```
+
+Then open your browser to `http://localhost:5173`.
+
+---
+
+## ⚙️ Configuration
+
+When initialized, TactiTerm automatically generates a `config.json` file in the root directory if one does not exist.
+
+### `config.json` Example
+
+```json
+{
+  "llm": {
+    "base_url": "http://localhost:8080/v1",
+    "model": "local-model",
+    "api_key": "not-needed",
+    "temperature": 0.7,
+    "max_tokens": 512,
+    "timeout_seconds": 60.0
+  },
+  "web": {
+    "host": "127.0.0.1",
+    "port": 8000,
+    "public": false
+  }
+}
+```
+
+### Key Settings
+
+- **LLM Settings:** Point `base_url` to any OpenAI-compatible server (LocalAI, vLLM, Ollama, LM Studio, or OpenAI API).
+- **Web UI Public Access:** Set `"public": true` under `"web"` (or set environment variable `TACTTERM_WEB_PUBLIC=true`) to bind the server to `0.0.0.0`, allowing other devices on your local network to connect.
+
+### Environment Variable Overrides
+
+- `TACTTERM_LLM_BASE_URL` - Override LLM API URL.
+- `TACTTERM_LLM_MODEL` - Override LLM model name.
+- `TACTTERM_WEB_HOST` - Override web server bind address.
+- `TACTTERM_WEB_PORT` - Override web server port (default: 8000).
+- `TACTTERM_WEB_PUBLIC` - Set to `true` to enable network binding (`0.0.0.0`).
+
+---
+
+## 🏗️ Architecture
+
+- **Backend (`src/api/main.py`):** FastAPI application serving REST endpoints for challenges, code linting, code execution, mentoring guidance, and handbook references.
+- **Core Engine (`src/core/`):**
+  - `config.py`: Application config manager with auto-generation and env overrides.
+  - `executor.py`: Subprocess execution engine for multi-language code snippets.
+  - `linter.py`: Tree-sitter syntax checker.
+  - `mentor.py`: Async Socratic mentor prompt & LLM service.
+  - `handbook.py`: Reference catalog and example generator.
+  - `generator.py`: AI challenge generation service.
+- **TUI Client (`src/tui/`):** Textual terminal application.
+- **Web Client (`frontend/`):** React + TypeScript SPA powered by Vite, Tailwind CSS, and Monaco Editor.
+
+---
+
+## 📜 License
+
+MIT License. See `LICENSE` for details.