empire-core 0.1.0__tar.gz

empire_core-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  lint:
+    name: Lint & Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run pre-commit
+        uses: pre-commit/action@v3.0.1
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run tests
+        run: uv run pytest -v

empire_core-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,76 @@
+name: Release
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+    branches: [master]
+  workflow_dispatch:
+
+jobs:
+  release:
+    name: Semantic Release
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
+    concurrency: release
+    permissions:
+      contents: write
+    outputs:
+      released: ${{ steps.release.outputs.released }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Semantic Release
+        id: release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          output=$(uv run semantic-release version 2>&1) || true
+          echo "$output"
+          if echo "$output" | grep -q "No release will be made"; then
+            echo "released=false" >> $GITHUB_OUTPUT
+          elif [ -d "dist" ] && [ "$(ls -A dist)" ]; then
+            echo "released=true" >> $GITHUB_OUTPUT
+            uv run semantic-release publish
+          else
+            echo "released=false" >> $GITHUB_OUTPUT
+          fi
+
+  publish:
+    name: Publish to PyPI
+    needs: release
+    if: needs.release.outputs.released == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

empire_core-0.1.0/.gitignore

@@ -0,0 +1,138 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   with no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Config
+accounts.json
+*.db
+*.db-shm
+*.db-wal

empire_core-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+# Pre-commit configuration for EmpireCore
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.1.14
+    hooks:
+      - id: ruff
+        args: [ --fix ]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.8.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [ pydantic, aiohttp, python-dotenv, typer, sqlmodel, aiosqlite, sqlalchemy, types-tabulate ]
+        args: []
+
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v3.1.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [ commit-msg ]
+        args: []

empire_core-0.1.0/GEMINI.md

@@ -0,0 +1,48 @@
+# EmpireCore - AI Context File
+
+## Project Overview
+**EmpireCore** is a modern, async Python library for automating the browser game *Goodgame Empire*.
+It provides a high-level, type-safe API for interacting with the game server via WebSocket (SmartFoxServer protocol).
+
+---
+
+## Technical Stack & Tooling
+*   **Package Manager**: `uv` (standard for this repo).
+*   **Build System**: `hatchling` (PEP 621).
+*   **Linter/Formatter**: `ruff`.
+*   **Type Checker**: `mypy`.
+*   **Git Hooks**: `pre-commit` (configured for Ruff, Mypy, and Conventional Commits).
+
+---
+
+## Core Architecture
+
+### 1. Account System (`empire_core.accounts`)
+The entry point for all automation.
+*   **`AccountRegistry` (`accounts`)**: Singleton that loads credentials from `accounts.json`.
+*   **`Account`**: Represents a game account. Use `account.get_client()` to start.
+
+### 2. The Client (`empire_core.client`)
+*   **Composition over Inheritance**: Features are exposed via composed services.
+    *   `client.quests`, `client.reports`, `client.alliance`, `client.chat`, `client.defense`.
+
+### 3. State Management (`empire_core.state`)
+*   **`GameState`**: The source of truth. Updated automatically by incoming packets.
+*   **Models**: Pydantic v2 models for type safety.
+
+---
+
+## Development Guidelines
+
+1.  **Conventional Commits**: All commits must follow the `feat:`, `fix:`, `refactor:` pattern.
+2.  **Type Safety**: `mypy` must pass with zero errors. Always use type hints.
+3.  **No God Objects**: Keep `EmpireClient` lean. Add logic to Services or Managers.
+4.  **CLI first**: New high-level status or diagnostic features should be added to `cli.py`.
+
+## Essential Commands
+```bash
+uv sync --extra dev      # Sync all dependencies
+uv run empire status     # CLI check
+uv run pytest            # Run tests
+uv run pre-commit run --all-files # Final check before commit
+```

empire_core-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: empire-core
+Version: 0.1.0
+Summary: Asynchronous Python framework for Goodgame Empire
+Project-URL: Repository, https://github.com/eschnitzler/EmpireCore
+Author-email: E Joseph <east1499@gmail.com>
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: aiosqlite>=0.19.0
+Requires-Dist: pydantic>=2.5
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: sqlmodel>=0.0.14
+Requires-Dist: tabulate>=0.9.0
+Requires-Dist: tqdm>=4.66.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: python-semantic-release>=9.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: sqlalchemy[mypy]; extra == 'dev'
+Requires-Dist: types-tabulate; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+">
+  <img src="https://img.shields.io/badge/asyncio-powered-green.svg" alt="Asyncio">
+  <img src="https://img.shields.io/badge/pydantic-v2-purple.svg" alt="Pydantic v2">
+  <img src="https://img.shields.io/badge/tool-uv-orange.svg" alt="UV">
+  <img src="https://img.shields.io/badge/status-WIP-red.svg" alt="Work in Progress">
+</p>
+
+<h1 align="center">EmpireCore</h1>
+
+<p align="center">
+  <strong>Modern async Python library for Goodgame Empire automation</strong>
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> •
+  <a href="#installation">Installation</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#examples">Examples</a> •
+  <a href="#documentation">Documentation</a>
+</p>
+
+---
+
+> **⚠️ Work in Progress**
+> 
+> This library is under active development. APIs may change, and some features are incomplete or untested. Use at your own risk.
+
+---
+
+## Features
+
+| Category | Capabilities |
+|----------|-------------|
+| **Connection** | WebSocket, auto-reconnect, login cooldown handling |
+| **State Tracking** | Player, castles, resources, buildings, units, movements |
+| **Actions** | Attacks, transports, recruiting, building, with response validation |
+| **Automation** | Task loops, multi-account, target finder, map scanner |
+| **CLI** | Account status, login testing, state summary |
+
+## Installation
+
+This project uses [uv](https://github.com/astral-sh/uv) for blazing-fast dependency management.
+
+```bash
+git clone https://github.com/eschnitzler/EmpireCore.git
+cd EmpireCore
+
+# Install dependencies and create venv automatically
+uv sync
+```
+
+### Traditional Installation (Pip)
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install .
+```
+
+## Configuration
+
+Create an `accounts.json` file in the root directory. You can use the provided template:
+
+```bash
+cp accounts.json.template accounts.json
+```
+
+Then edit `accounts.json` with your credentials. This file is git-ignored to keep your credentials safe.
+
+## Quick Start
+
+```python
+import asyncio
+from empire_core import accounts
+
+async def main():
+    # Load default account from accounts.json
+    account = accounts.get_default()
+    if not account:
+        print("Please configure accounts.json first!")
+        return
+
+    # Create client directly from account object
+    client = account.get_client()
+    
+    await client.login()
+    await client.get_detailed_castle_info()
+    
+    player = client.state.local_player
+    print(f"{player.name} | Level {player.level} | {player.gold} gold")
+    
+    await client.close()
+
+asyncio.run(main())
+```
+
+## CLI Tool
+
+The library includes a CLI for quick operations:
+
+```bash
+# Check configured accounts
+uv run empire status
+
+# Test login and show player stats
+uv run empire login
+```
+
+## Running Examples & Tests
+
+```bash
+# Run the demo
+uv run examples/demo.py
+
+# Run unit tests
+uv run pytest
+```
+
+## Development
+
+We use `ruff` for linting and `mypy` for type checking.
+
+```bash
+# Setup pre-commit hooks
+uv run pre-commit install
+
+# Run all checks manually
+uv run pre-commit run --all-files
+```
+
+---
+
+<p align="center">
+  <sub>For educational purposes only. Use responsibly.</sub>
+</p>

empire_core-0.1.0/README.md

@@ -0,0 +1,135 @@
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+">
+  <img src="https://img.shields.io/badge/asyncio-powered-green.svg" alt="Asyncio">
+  <img src="https://img.shields.io/badge/pydantic-v2-purple.svg" alt="Pydantic v2">
+  <img src="https://img.shields.io/badge/tool-uv-orange.svg" alt="UV">
+  <img src="https://img.shields.io/badge/status-WIP-red.svg" alt="Work in Progress">
+</p>
+
+<h1 align="center">EmpireCore</h1>
+
+<p align="center">
+  <strong>Modern async Python library for Goodgame Empire automation</strong>
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> •
+  <a href="#installation">Installation</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#examples">Examples</a> •
+  <a href="#documentation">Documentation</a>
+</p>
+
+---
+
+> **⚠️ Work in Progress**
+> 
+> This library is under active development. APIs may change, and some features are incomplete or untested. Use at your own risk.
+
+---
+
+## Features
+
+| Category | Capabilities |
+|----------|-------------|
+| **Connection** | WebSocket, auto-reconnect, login cooldown handling |
+| **State Tracking** | Player, castles, resources, buildings, units, movements |
+| **Actions** | Attacks, transports, recruiting, building, with response validation |
+| **Automation** | Task loops, multi-account, target finder, map scanner |
+| **CLI** | Account status, login testing, state summary |
+
+## Installation
+
+This project uses [uv](https://github.com/astral-sh/uv) for blazing-fast dependency management.
+
+```bash
+git clone https://github.com/eschnitzler/EmpireCore.git
+cd EmpireCore
+
+# Install dependencies and create venv automatically
+uv sync
+```
+
+### Traditional Installation (Pip)
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install .
+```
+
+## Configuration
+
+Create an `accounts.json` file in the root directory. You can use the provided template:
+
+```bash
+cp accounts.json.template accounts.json
+```
+
+Then edit `accounts.json` with your credentials. This file is git-ignored to keep your credentials safe.
+
+## Quick Start
+
+```python
+import asyncio
+from empire_core import accounts
+
+async def main():
+    # Load default account from accounts.json
+    account = accounts.get_default()
+    if not account:
+        print("Please configure accounts.json first!")
+        return
+
+    # Create client directly from account object
+    client = account.get_client()
+    
+    await client.login()
+    await client.get_detailed_castle_info()
+    
+    player = client.state.local_player
+    print(f"{player.name} | Level {player.level} | {player.gold} gold")
+    
+    await client.close()
+
+asyncio.run(main())
+```
+
+## CLI Tool
+
+The library includes a CLI for quick operations:
+
+```bash
+# Check configured accounts
+uv run empire status
+
+# Test login and show player stats
+uv run empire login
+```
+
+## Running Examples & Tests
+
+```bash
+# Run the demo
+uv run examples/demo.py
+
+# Run unit tests
+uv run pytest
+```
+
+## Development
+
+We use `ruff` for linting and `mypy` for type checking.
+
+```bash
+# Setup pre-commit hooks
+uv run pre-commit install
+
+# Run all checks manually
+uv run pre-commit run --all-files
+```
+
+---
+
+<p align="center">
+  <sub>For educational purposes only. Use responsibly.</sub>
+</p>

empire_core-0.1.0/STATUS.md

@@ -0,0 +1,59 @@
+# EmpireCore Status
+
+## Current Status: PRODUCTION READY 🚀
+
+The core API, state management, and modern toolchain are implemented and verified.
+
+---
+
+## What's Working
+
+### 1. Modern Toolchain (NEW)
+- [x] `uv` for dependency management & lightning-fast builds
+- [x] PEP 621 compliant `pyproject.toml`
+- [x] `ruff` for ultra-fast linting and formatting
+- [x] `mypy` for 100% type safety in the core library
+- [x] `pre-commit` hooks for automatic quality checks
+- [x] CLI Tool (`uv run empire`) for account & login management
+
+### 2. Login & Authentication
+- [x] Robust `AccountRegistry` supporting `accounts.json`
+- [x] `Account` objects as primary entry points (`account.get_client()`)
+- [x] WebSocket handshake and XT authentication
+- [x] Login cooldown (Error 453) detection & handling
+
+### 3. State Tracking & Services
+- [x] Service-based composition (`client.quests`, `client.reports`, etc.)
+- [x] Real-time state updates from SFS packets
+- [x] Comprehensive Pydantic models for Players, Castles, and World objects
+- [x] Real-time movement tracking and arrival events
+
+### 4. Game Actions
+- [x] Attacks, scouts, and transports
+- [x] Building upgrades and unit recruitment
+- [x] Tax collection and item usage
+- [x] Private and alliance chat messaging
+
+### 5. Automation Framework
+- [x] `tasks.loop` decorator (discord.py style)
+- [x] `MapScanner` for spiral exploration
+- [x] `BuildingManager` with priority queues
+- [x] `MultiAccountManager` for multi-session operations
+
+---
+
+## Project Structure
+
+```
+empire_core/
+├── accounts.py     # AccountRegistry and Account models
+├── cli.py          # Click/Typer CLI implementation
+├── client/         # Client and Service logic
+├── state/          # Game state and Pydantic models
+├── automation/     # Background tasks and managers
+└── network/        # SFS protocol and WebSocket handling
+```
+
+---
+
+**Last Updated:** December 21, 2025