# 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.

---