Textual Terminal UI (TUI)

Overview

The Artifact Miner TUI provides a modern, interactive terminal interface built with Python Textual. Navigate through screens using keyboard and mouse, with real-time feedback and visual progress indicators.

Installation

The TUI is included with Artifact Miner:

pip install artifactminer
# or
uv pip install artifactminer

Launching the TUI

Start the Textual interface:

python -m artifactminer.tui.app
# or
uv run python -m artifactminer.tui.app

Application Flow

The TUI guides you through a multi-screen workflow:

Welcome Screen

Initial landing page with branding and call-to-action.

╔════════════════════════════════════════════════════╗
║                                                    ║
║              ARTIFACT-MINER                        ║
║      Welcome to the artifact staging tool.        ║
║                                                    ║
║              [ Start Mining ]                      ║
║                                                    ║
╚════════════════════════════════════════════════════╝

Actions:

Click Start Mining button to begin
Press q to quit

Consent Screen

Choose data processing consent level with detailed explanation.The screen displays:

Full consent agreement text in scrollable container
What data is collected (metadata, file contents, timestamps)
Your data rights and permissions
LLM processing options

╔════════════════════════════════════════════════════╗
║         Data Usage Consent                         ║
║────────────────────────────────────────────────────║
║  # Consent Required                                ║
║                                                    ║
║  By using Artifact Miner, you consent to the      ║
║  collection and analysis of artifacts from the    ║
║  provided .zip file.                              ║
║                                                    ║
║  ## What We Collect                               ║
║  - Artifact metadata (file names, paths, types)   ║
║  - File contents for analysis purposes            ║
║  - Timestamps of when artifacts were scanned      ║
║                                                    ║
║  ## LLM Processing Options                        ║
║  - Consent with LLM: External LLM services used   ║
║  - Consent without LLM: Local processing only     ║
║────────────────────────────────────────────────────║
║  [ Consent with LLM ]  [ Consent without LLM ]    ║
║                                                    ║
║  Select a consent option to continue.             ║
║  [ Back ]                    [ Continue ]         ║
╚════════════════════════════════════════════════════╝

Workflow:

Click Consent with LLM (green) or Consent without LLM (blue)
Selection is highlighted and status updates
Click Continue to proceed
Consent is saved to backend via API call

Status Messages:

"Consent with LLM selected." - Full consent chosen
"Consent without LLM selected." - No external LLM processing
"Saving consent choice..." - API request in progress
"Consent saved. Loading preferences..." - Success
"Cannot connect to the backend server." - Connection error (red)

User Config Screen

Enter user information (email address) for personalization.

╔════════════════════════════════════════════════════╗
║     Enter your email address:                      ║
║  ┌──────────────────────────────────────────────┐  ║
║  │ [email protected]                       │  ║
║  └──────────────────────────────────────────────┘  ║
║                                                    ║
║  [ Back ]                    [ Continue ]         ║
╚════════════════════════════════════════════════════╝

Actions:

Type your email address in the input field
Click Continue to proceed
Email is stored for tracking and resume generation

Upload Screen

Select and upload a ZIP file containing your projects.

╔════════════════════════════════════════════════════╗
║  Enter a path to a .zip file.                      ║
║  ┌──────────────────────────────────────────────┐  ║
║  │ ~/Desktop/projects.zip                       │  ║
║  └──────────────────────────────────────────────┘  ║
║          [ Browse ]  [ Upload ]                    ║
║                                                    ║
║  Waiting for a file...                            ║
║  [ Back ]                                          ║
╚════════════════════════════════════════════════════╝

Three ways to select a file:

Manual Entry
Browse Button
Drag & Drop

Type the full path to your ZIP file:

~/Desktop/my-projects.zip
/home/student/portfolio.zip

Click Browse to open an interactive file browser:

Navigate directories using arrow keys or mouse
Select .zip files
Double-click or press Enter to select

Status Messages:

"Waiting for a file..." - Initial state
"Please enter a path." - Empty input submitted
"File not found: [path]" - Path doesn’t exist
"Need a .zip file." - Wrong file extension
"Uploading and fetching contents..." - Upload in progress
"No contents found in archive." - Empty ZIP file

After successful upload:

ZIP is uploaded to backend
Contents are extracted and scanned
Transitions to Directory Selection screen

Directory Selection Screen

Choose which directories/repositories to analyze from the ZIP archive.

╔════════════════════════════════════════════════════╗
║         Contents of ZIP File                       ║
║────────────────────────────────────────────────────║
║  ┌────────────────────────────────────────────┐    ║
║  │ ☑ portfolio-website                        │    ║
║  │ ☑ ml-classifier                            │    ║
║  │ ☐ react-dashboard                          │    ║
║  │ ☑ python-automation                        │    ║
║  │ ☐ discord-bot                              │    ║
║  └────────────────────────────────────────────┘    ║
║                                                    ║
║  Selected 3 files                                  ║
║  [ Back ]              [ Select Files ]            ║
╚════════════════════════════════════════════════════╝

Features:

Scrollable list of all directories in ZIP
Click checkboxes to toggle selection
Selection count updates in real-time
Select Files button disabled until at least one item selected
Filters out macOS metadata (__MACOSX/, ._* files)

Keyboard Navigation:

↑/↓ - Move between items
Space - Toggle checkbox
Tab - Switch between list and buttons
Enter - Activate focused button

Analyzing Screen

Real-time progress display during analysis.

╔════════════════════════════════════════════════════╗
║         Analyzing Projects...                      ║
║────────────────────────────────────────────────────║
║  ⠋ Processing repositories...                      ║
║                                                    ║
║  ████████████████░░░░░░░░░░░  60%                 ║
║                                                    ║
║  Current: react-dashboard (2/3)                   ║
║                                                    ║
║  Completed:                                        ║
║    ✓ portfolio-website                            ║
║    ✓ ml-classifier                                │
║    ⟳ react-dashboard (in progress)               ║
║────────────────────────────────────────────────────║
║  Extracting git history...                        ║
╚════════════════════════════════════════════════════╝

Display Elements:

Animated spinner for ongoing activity
Progress bar showing percentage complete
Current repository being analyzed
List of completed repositories with checkmarks
Status messages for current operation

Automatically transitions to Resume Screen when complete

Resume & Summaries Screen

View and export generated resume items and AI summaries.

╔════════════════════════════════════════════════════╗
║       Resume & Summaries                           ║
║────────────────────────────────────────────────────║
║  ┌────────────────────────────────────────────┐    ║
║  │ 📁 portfolio-website                       │    ║
║  │ ─────────────────────────────────────      │    ║
║  │ • Responsive Portfolio Development         │    ║
║  │   Developed responsive portfolio website  │    ║
║  │   using React and Next.js with SSR...     │    ║
║  │                                            │    ║
║  │ • Performance Optimization                 │    ║
║  │   Optimized bundle size by 40% using...   │    ║
║  │                                            │    ║
║  │ ┌──────────────────────────────────────┐  │    ║
║  │ │ 💡 AI Summary:                       │  │    ║
║  │ │ A modern portfolio website built... │  │    ║
║  │ └──────────────────────────────────────┘  │    ║
║  │                                            │    ║
║  │ 📁 ml-classifier                           │    ║
║  │ ─────────────────────────────────────      │    ║
║  │ • Machine Learning Model Development       │    ║
║  └────────────────────────────────────────────┘    ║
║  Loaded 12 items.                                  ║
║  [ Export JSON ]  [ Export Text ]                  ║
║  [ Back ]  [ Projects ]  [ Skills ]                ║
╚════════════════════════════════════════════════════╝

Content Display:

Resume items grouped by project with folder icons
Item titles in bold
Content preview (first 200 characters, dimmed text)
AI summaries in highlighted boxes with lightbulb icon (when available)
Scrollable content area for long lists

Export Options:

Export JSON
Export Text

Click Export JSON to save structured data:

Generates timestamped file: resume_export_YYYYMMDD_HHMMSS.json
Includes all resume items and summaries
Saved to current directory
Shows notification with filename

Click Export Text to save human-readable report:

Generates timestamped file: resume_export_YYYYMMDD_HHMMSS.txt
Formatted with sections and bullet points
Saved to current directory
Shows notification with filename

Navigation:

Back - Return to previous screen

File Browser

When you click Browse on the Upload screen, an interactive file browser opens:

╔════════════════════════════════════════════════════╗
║         Select a ZIP File                          ║
║────────────────────────────────────────────────────║
║  📁 /home/student                                   ║
║  ┌────────────────────────────────────────────┐    ║
║  │ 📁 ../                                     │    ║
║  │ 📁 Desktop/                                │    ║
║  │ 📁 Documents/                              │    ║
║  │ 📁 Downloads/                              │    ║
║  │ 📄 projects.zip                            │    ║
║  │ 📄 portfolio.zip                           │    ║
║  └────────────────────────────────────────────┘    ║
║                                                    ║
║  [ Cancel ]                   [ Select ]           ║
╚════════════════════════════════════════════════════╝

Features:

Directory tree navigation
Only shows .zip files and directories
Click ../ to go up one level
Double-click directory to enter
Single-click file to select
Current path shown at top

Keyboard Shortcuts

Global shortcuts available throughout the TUI:

Key	Action
`q`	Quit application
`Ctrl+C`	Force quit
`Tab`	Switch focus between UI elements
`Shift+Tab`	Switch focus backwards
`Enter`	Activate focused button/selection
`Esc`	Go back / Cancel

Screen-specific shortcuts:

Screen	Key	Action
Directory Selection	`↑`/`↓`	Navigate list
Directory Selection	`Space`	Toggle checkbox
Resume Screen	`Page Up`/`Page Down`	Scroll content
File Browser	`Enter`	Open directory / Select file

API Integration

The TUI communicates with the Artifact Miner backend API at http://127.0.0.1:8000:

Consent Endpoints

Upload Endpoints

POST /upload - Upload ZIP file

Multipart form data with file
Returns zip_id for tracking

GET /zip//directories - List ZIP contents

{
  "directories": [
    "portfolio-website/",
    "ml-classifier/",
    "react-dashboard/"
  ]
}

Analysis Endpoints

POST /analyze/ - Start analysis

Optionally specify directories to analyze
Returns analysis results

GET /resume_items - Fetch resume itemsGET /summaries - Fetch AI summaries

Error Handling

The TUI provides user-friendly error messages:

Connection Errors
File Errors
API Errors

╔════════════════════════════════════════════╗
║  ⚠ Cannot connect to API server           ║
║                                            ║
║  Make sure the backend is running:         ║
║  $ python -m artifactminer.api.main        ║
╚════════════════════════════════════════════╝

Notification: “Cannot connect to the backend server. Is it running?”

File not found: /path/to/missing.zip

Need a .zip file.

No contents found in archive.

╔════════════════════════════════════════════╗
║  ⚠ Server error: 500                       ║
║                                            ║
║  HTTP 500 error.                           ║
╚════════════════════════════════════════════╝

Styling and Themes

The TUI uses Textual’s theming system with custom CSS:

Primary color: Blue for main actions
Success color: Green for confirmations
Warning color: Yellow for cautions
Error color: Red for errors
Surface: Rounded borders for containers
Panel: Elevated card-like components
Boost: Subtle background highlights

Running the Backend

The TUI requires the Artifact Miner API to be running:

# Start the backend in a separate terminal
python -m artifactminer.api.main

# Or with uvicorn
uvicorn artifactminer.api.main:app --reload

# Then launch the TUI
python -m artifactminer.tui.app

Backend runs on: http://127.0.0.1:8000

Advantages Over CLI

Visual Feedback

See real-time progress, completion status, and results in formatted displays

Interactive Selection

Click checkboxes to select specific projects instead of typing numbers

Error Prevention

UI validates inputs and disables invalid actions before they occur

Guided Workflow

Screen-by-screen flow prevents missing steps or incorrect configurations

Limitations

Requires API backend to be running
Not suitable for scripting or automation
Limited to terminal window size
Mouse support varies by terminal emulator

Next Steps

CLI Interface

Learn about the command-line interface for automation

React Client

Try the experimental OpenTUI React client

API Documentation

Explore the backend API endpoints

Development Setup

Set up a development environment

Get Started

Core Features

User Interfaces

Guides

Overview

Installation

Launching the TUI

Application Flow

File Browser

Keyboard Shortcuts

API Integration

Error Handling

Styling and Themes

Running the Backend

Advantages Over CLI

Visual Feedback

Interactive Selection

Error Prevention

Guided Workflow

Limitations

Next Steps

CLI Interface

React Client

API Documentation

Development Setup

Build docs developers (and LLMs) love

Get Started

Core Features

User Interfaces

Guides

​Overview

​Installation

​Launching the TUI

​Application Flow

​File Browser

​Keyboard Shortcuts

​API Integration

​Error Handling

​Styling and Themes

​Running the Backend

​Advantages Over CLI

Visual Feedback

Interactive Selection

Error Prevention

Guided Workflow

​Limitations

​Next Steps

CLI Interface

React Client

API Documentation

Development Setup

Build docs developers (and LLMs) love

Overview

Installation

Launching the TUI

Application Flow

File Browser

Keyboard Shortcuts

API Integration

Error Handling

Styling and Themes

Running the Backend

Advantages Over CLI

Limitations

Next Steps