Skip to content

README.md

Latest commit

 

History

History
301 lines (225 loc) · 9.01 KB

README.md

File metadata and controls

301 lines (225 loc) · 9.01 KB

TamaLLM 🐾

A Tamagotchi-like terminal game with a local LLM "brain" powered by Ollama.

image

Features

  • Real-time pet simulation - Stats decay over time, evolution through life stages, and care-dependent outcomes
  • Beautiful Terminal UI - Built with Charm's Bubble Tea framework with colorful stat bars and ASCII art
  • LLM-Powered Personality - Your pet speaks with a unique personality using a local Ollama model
  • Tool Calling - The LLM can propose events and set moods through a safe, bounded tool system
  • Persistent Save - Your pet persists across sessions with automatic saving
  • Deterministic Gameplay - Game rules are deterministic; the LLM only adds flavor

Quick Start

Prerequisites

  1. Go 1.21+ - Install Go
  2. Ollama - Install Ollama

Setup

# Clone the repository
git clone https://github.com/danielmerja/TamaLLM.git
cd TamaLLM

# Pull the recommended model
ollama pull qwen3:1.7b

# Build and run
go run ./cmd/tamallm

Run Without LLM

If you don't have Ollama installed or want to play without AI features:

go run ./cmd/tamallm --no-llm

Controls

Key Action
Enter / Space Select / Open menu
↑/k, ↓/j Navigate menus
Esc / Backspace Go back
m Open action menu
a Toggle LLM auto mode
? Toggle help
d Toggle debug mode
q Quit (auto-saves)

Debug Mode

Press d to toggle debug mode, which displays:

  • LLM Enabled/Pending/Auto status - Shows if LLM is active and processing
  • TTS status - Shows TTS availability and any errors (e.g., "Available (via python3, voice: M2)" or "Unavailable: supertonic not found")
  • Last LLM Input - The action that triggered the LLM request
  • Last LLM Output - The pet's message from the LLM
  • Pet Said - The current pet message being displayed
  • Age and Stage - Pet's current age and life stage
  • Care Score - Running average of care quality
  • Suggested Action - (Auto mode only) The next recommended action

Gameplay

Life Stages

Your pet evolves through 5 stages based on age and care quality:

  1. Egg 🥚 - Hatches after ~30 seconds
  2. Baby 🐣 - Grows to child after ~2 minutes
  3. Child 🐥 - Becomes teenager after ~5 minutes
  4. Teen 🐤 - Evolves to adult after ~10 minutes
  5. Adult 🐔 - Final form depends on care quality!

Adult Types

The type of adult your pet becomes depends on how well you cared for them:

  • Healthy Adult - Good stats, few sickness events, balanced discipline
  • Chubby Adult - Overfed with too many snacks
  • Naughty Adult - Low discipline from lack of training
  • Negligence Adult - Poor overall care quality

Stats

Keep these stats healthy (above 30) to keep your pet happy:

  • Hunger 🍽️ - Feed meals and snacks
  • Happiness 😊 - Play games and give praise
  • Energy ⚡ - Let your pet sleep when tired
  • Hygiene 🛁 - Clean regularly to prevent sickness
  • Health ❤️ - Give medicine when sick

Actions

Action Effect
Feed Meal +30 Hunger, +5 Happiness, +1 Weight
Feed Snack +10 Hunger, +15 Happiness, chance +1 Weight
Give Treat +20 Happiness, +5 Hunger, high chance +1 Weight
Play +25 Happiness, -20 Energy, -10 Hunger
Exercise +15 Happiness, -25 Energy, -15 Hunger, +5 Health, +3 Discipline
Explore +10 Happiness, -10 Energy, random encounters
Train +8 Discipline, -15 Energy
Clean +40 Hygiene, +5 Happiness
Sleep Restores Energy over time
Medicine Cures sickness, +20 Health
Praise +10 Happiness, slight -2 Discipline
Scold +10 Discipline, -15 Happiness

LLM Auto Mode

Press a or start with --auto to enable LLM-driven automatic care:

  • The LLM will automatically perform actions when needed
  • It uses the get_suggested_action tool to determine the best action
  • Great for letting your pet care for itself while you watch!

Configuration

Environment Variables

Variable Default Description
OLLAMA_HOST http://localhost:11434 Ollama server URL
OLLAMA_MODEL qwen3:1.7b Model to use
OLLAMA_TIMEOUT 10s Request timeout
OLLAMA_THINK off Thinking mode (off/low/medium/high)

CLI Flags

go run ./cmd/tamallm [flags]

Flags:
  --new           Start a new game (ignore existing save)
  --model NAME    Override Ollama model
  --host URL      Override Ollama host URL
  --tick-ms N     Simulation tick interval (default: 1000)
  --no-llm        Run without LLM (use canned messages)
  --auto          Start with LLM auto mode enabled
  --tts           Enable Text-to-Speech (requires Supertonic-2)
  --tts-voice     TTS voice style (M1-M5, F1-F5, default: F3)

Text-to-Speech (Supertonic-2)

TamaLLM supports text-to-speech using the Supertonic-2 model from Supertone. This allows your pet to "speak" its messages out loud!

Setup TTS

  1. Install Python 3.8+ and pip

  2. Install the Supertonic package:

    pip install supertonic sounddevice soundfile

    Using uv (recommended):

    uv venv
uv pip install supertonic sounddevice soundfile

  3. Run with TTS enabled:

    go run ./cmd/tamallm --tts

    TamaLLM automatically detects and uses uv run when packages are installed via uv pip install in a uv venv environment.

Voice Styles

Style Description
M1-M5 Male voices with varying tones
F1-F5 Female voices with varying tones

Example with custom voice:

go run ./cmd/tamallm --tts --tts-voice M2

Recommended Models

Model Size Notes
qwen3:1.7b ~1.5GB Default, fast, good quality
qwen3:4b ~2.5GB Better responses, still fast
qwen3:8b ~5.2GB High quality, requires more RAM

Development

Project Structure

TamaLLM/
├── cmd/tamallm/          # Main entry point
│   └── main.go
├── internal/
│   ├── game/             # Pure game engine
│   │   ├── state.go      # Pet state struct
│   │   ├── engine.go     # Game logic
│   │   └── engine_test.go
│   ├── tui/              # Terminal UI
│   │   ├── model.go      # Bubble Tea model
│   │   └── views.go      # View rendering
│   ├── llm/              # Ollama integration
│   │   ├── client.go     # API client
│   │   └── client_test.go
│   ├── tts/              # Text-to-Speech (Supertonic-2)
│   │   ├── tts.go        # TTS client
│   │   └── tts_test.go
│   ├── storage/          # Save/load
│   │   ├── storage.go
│   │   └── storage_test.go
│   └── util/             # Helpers
│       ├── util.go
│       └── util_test.go
├── go.mod
├── go.sum
└── README.md

Running Tests

# Run all tests
go test ./...

# Run with coverage
go test -cover ./...

# Run specific package tests
go test ./internal/game/

Building

# Build binary
go build -o tamallm ./cmd/tamallm

# Build with optimizations
go build -ldflags="-s -w" -o tamallm ./cmd/tamallm

Architecture

Bubble Tea Patterns

The TUI follows Bubble Tea best practices:

  • Never blocks Update() with network I/O
  • Uses tea.Cmd for async work (ticks, LLM calls, saves)
  • Uses tea.Tick for simulation ticks

LLM Integration

The LLM integration is:

  • Safe - Tool calls are validated and bounded
  • Optional - Game works fine without LLM
  • Action-driven - LLM can request actions through validated tools
  • Interface-driven - Easy to mock for testing

Tool Calling

When tool calling is enabled, the LLM can use these tools:

Tool Description Permissions
rand_int(min, max) Generate random number Read-only
propose_event(type, severity, desc) Propose game event Validated by engine
set_mood(mood, emoji, intensity) Set UI mood display UI-only
summarize_state() Get state summary Read-only
request_action(action) Request to perform an action Validated and executed
get_valid_actions() Get list of currently valid actions Read-only
get_suggested_action() Get suggested action based on needs Read-only

Save File

Saves are stored in XDG-compliant locations:

  • Linux: ~/.local/share/tamallm/tamallm_save.json
  • macOS: ~/Library/Application Support/tamallm/tamallm_save.json

Save format is versioned JSON for forward compatibility.

License

MIT License - see LICENSE file for details.

Credits

  • Built with Bubble Tea by Charm
  • LLM runtime by Ollama
  • Inspired by the classic Tamagotchi virtual pets