TactiTerm/README.md

TactiTerm

<<<<<<< HEAD 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 (Python package runner)
• Node.js & npm (for Web UI)
• Devbox (optional, for reproducible envs)

Installation

1. Clone the repository:

   git clone https://github.com/your-username/TactiTerm.git
   cd TactiTerm
   

2. Install dependencies:

   make install
   

---

🎮 Usage

Terminal Interface (TUI)

Launch the interactive terminal application:

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:

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

{
  "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.

Tactile Terminal: A WebUI / TUI built to help teach and and study programming concepts in an interactive way.

branch 'main' of https://git.dewm.ca/dewm/TactiTerm.git