Metadata-Version: 2.4
Name: tgoti
Version: 0.0.1
Summary: Terminal Tamagotchi for stocks — each pet is a real or simulated Alpaca position
Project-URL: Homepage, https://github.com/joeltco/tgoti
Project-URL: Repository, https://github.com/joeltco/tgoti
Project-URL: Issues, https://github.com/joeltco/tgoti/issues
Author: joeltco
License: MIT License
        
        Copyright (c) 2026 joeltco
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        ---
        
        Note on third-party assets:
        
        The sprite source pack at `tools/sprite_sources/tiny-creatures/` is a
        separate CC0 work by its original author. See the `License.txt` file in
        that directory for its terms. The MIT license above covers everything
        else in this repository.
License-File: LICENSE
Keywords: alpaca,finance,game,stocks,tamagotchi,terminal,textual,trading,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Terminals
Requires-Python: >=3.11
Requires-Dist: textual>=0.80
Provides-Extra: alpaca
Requires-Dist: alpaca-py>=0.30; extra == 'alpaca'
Provides-Extra: dev
Requires-Dist: bandit>=1.7; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# tgoti

Terminal Tamagotchi for stocks. Each pet IS a real (or simulated) Alpaca
position; HP tracks unrealized P&L, feeding buys more of the symbol,
pets age only during NYSE market hours.

[![ci](https://github.com/joeltco/tgoti/actions/workflows/ci.yml/badge.svg)](https://github.com/joeltco/tgoti/actions/workflows/ci.yml)
[![python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
[![license: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![checks: ruff · mypy · bandit](https://img.shields.io/badge/checks-ruff%20%C2%B7%20mypy%20%C2%B7%20bandit-purple)](https://github.com/joeltco/tgoti/actions/workflows/ci.yml)

![tgoti — a terminal Tamagotchi for stocks](docs/screenshot.png)

```
 ████████  ██████  ██████  ████████  ██
    ██     ██      ██  ██     ██     ██
    ██     ██ ███  ██  ██     ██     ██
    ██     ██  ██  ██  ██     ██     ██
    ██     ██████  ██████     ██     ██
            stockpets
```

## Install

```bash
git clone git@github.com:joeltco/tgoti.git
cd tgoti
pip install -e .
```

Python 3.11+. Optional Alpaca SDK for paper/live: `pip install -e .[alpaca]`.

### Docker

```bash
docker build -t tgoti .
docker run -it --rm tgoti            # play in sandbox mode
docker run --rm tgoti --list-saves   # headless CLI ops
```

## Run

```bash
tgoti                  # default: sandbox
tgoti --mode paper     # Alpaca paper account
tgoti --mode live      # real money, $100/pet cap
```

Alpaca paper/live needs credentials at
`~/.config/alpaca-tui/credentials.yaml`:

```yaml
paper:
  api_key: PK...
  secret_key: ...
live:
  api_key: AK...
  secret_key: ...
```

## What it does

- **3 modes**: sandbox (local RNG, fast-forwards while you're away),
  paper (Alpaca paper), live (real money, $100/pet cap).
- **8 biomes** with themed ticker pools: meadow (blue chips), stormy
  (momentum), highlands (crypto), tide_pools (ETFs), volcanic (energy),
  frostlands (healthcare), ruins (legacy/value), forest (clean energy).
- **5-element type chart**: Fire → Ice → Storm → Earth → Spirit → Fire.
  Pet element = biome element. Matchup multiplies battle damage
  ×1.5 / ×1.0 / ×0.67.
- **3-tier monsters** weighted by pet stage. Eggs face mostly Tier 1;
  Legendaries face mostly Tier 3. 5% chance per battle of a boss roll
  (one boss per biome).
- **5 evolution stages**: Egg (0.1pd) → Baby → Junior (13pd) →
  Adult (32pd) → Legendary (100pd + positive P&L). "pd" = pet-day =
  1 hour of NYSE market time. Eggs hatch fast (~6 min market time) and
  are inert until they do.
- **Death conditions**: drawdown beyond
  `config.DEATH_DRAWDOWN_PCT` closes the position and graveyards the
  pet; manual release does the same with `reason='released by player'`.

See [docs/gameplay.md](docs/gameplay.md) for the full rules + keybindings.

## CLI

The game is a TUI but every read-only operation has a CLI flag. A few:

```bash
tgoti --list-saves                  # all saves, alive/dead/awake
tgoti --stats 3                     # plain-text stats for save #3
tgoti --pets 3 --sort hp            # alive pets, lowest-HP first
tgoti --events 12 --kind fed        # event log for pet #12
tgoti --search META                 # find pets by symbol across saves
tgoti --slayers --json              # pets with 3+ boss kills
tgoti --champions --top 10          # longest-lived across all saves
tgoti --tally --watch               # live cross-save summary
tgoti --doctor --json               # db + settings integrity check
tgoti --backup ~/tgoti-backup       # dump every save to JSON
```

`--watch` works with `--stats / --pets / --events / --leaderboard /
--tally / --list-saves`. `--json` works wherever there's tabular output.

`tgoti --help` lists everything.

## Development

```bash
pip install -e .[dev]

ruff check
mypy
bandit -c pyproject.toml -r tgoti/
pytest -q
```

All four run in CI on every push and PR (Python 3.11 + 3.12).

See [CONTRIBUTING.md](CONTRIBUTING.md) for project structure, the
sprite pipeline, and the test-isolation rule (every test must
inject `db_path` and `settings_path` — see existing `_fresh_app()`
helpers).

## License

MIT (see [LICENSE](LICENSE) once added). Sprite pack
(`tools/sprite_sources/tiny-creatures/`) is CC0 from the original
asset author — see `License.txt` in that directory.
