130 lines
4.3 KiB
Markdown
130 lines
4.3 KiB
Markdown
# TactiTerm
|
|
|
|
**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.
|
|
|
|
---
|