AICOC

AICOC is a local MVP for Clash of Clans base diagnosis and tactical planning. It takes a base screenshot, normalizes detections into structured layout data, retrieves similar replay cases, and produces a readable tactical summary through CLI or a small local web app.

This public repository is a code-first export. It intentionally excludes private media assets, downloaded videos, runtime caches, model checkpoints, and datasets whose redistribution status is unclear.

What It Does

Current MVP flow:

1. read one base screenshot
2. detect key buildings
3. normalize detections into a structured layout
4. run diagnosis and tactical planning rules
5. retrieve similar cases from a local replay memory
6. render a readable result in CLI or a local web app

Core capabilities:

• multiple detector modes: auto, roboflow, local_yolo, fixture, synthetic
• structured pipeline output instead of free-form text only
• replay memory retrieval and tactical planning
• optional Qwen-compatible planner and critic integration
• local HTML preview flow for iterative demos

Repository Layout

src/aicoc/          core pipeline, retrieval, planning, web server
scripts/            dataset and demo helper scripts
tests/              smoke tests, contract tests, fixtures
samples/            synthetic example inputs and templates
run_cli.py          CLI entrypoint
run_app.py          local web app entrypoint

Quick Start

1. Install

python -m pip install -r requirements.txt

Optional local YOLO support:

python -m pip install -r requirements-local-yolo.txt

For editable installs with test tooling:

python -m pip install -e .[dev]

2. Configure

copy .env.example .env

Recommended first-run mode for public users:

AICOC_DETECTOR=fixture
AICOC_COACH_PROVIDER=deterministic

3. Run the CLI

python run_cli.py --image "samples\\demo.png"
python run_cli.py --image "samples\\demo.png" --json

4. Run the local web app

python run_app.py

Then open http://127.0.0.1:8000.

Public Demo Assets

The public repository keeps only lightweight examples:

• samples/demo.png
• samples/demo.png.detections.json
• samples/public_candidate_metadata.template.json

These are intended for local development and fixture-based validation.

Detector Modes

auto

• use hosted Roboflow if env vars exist
• else use fixture if <image>.detections.json exists
• else use local YOLO if AICOC_LOCAL_YOLO_MODEL exists
• else use synthetic demo detections

roboflow

• requires ROBOFLOW_API_KEY
• requires ROBOFLOW_MODEL_ID

local_yolo

• requires AICOC_LOCAL_YOLO_MODEL
• requires ultralytics

fixture

• reads detections from a sidecar JSON file

synthetic

• returns deterministic demo detections

Testing

Lightweight smoke test:

python tests\\smoke_test.py

Pytest-based validation:

pytest

Note: some advanced workflows in the original private workspace depended on local media libraries, model checkpoints, or reconstructed datasets. Those assets are intentionally not included here.

Local Asset Policy

This repository is designed to be shared without bundling third-party replay videos, screenshots extracted from public platforms, private cookies, or local training outputs.

Recommended public/private split:

• public: source code, tests, synthetic fixtures, templates, docs
• private: replay videos, screenshots, datasets, model weights, logs, uploads

See ASSETS-NOTICE.md for details.

Known Limitations

• current public sample flow is designed around synthetic or fixture inputs
• local YOLO requires you to supply your own checkpoint path
• advanced replay-memory demos require a private local case library
• this MVP is optimized for a narrow strategy workflow rather than broad game coverage

Roadmap

• improve repository portability and packaging
• separate public templates from private replay-memory assets
• add cleaner public demo pages based only on synthetic assets
• reduce remaining Windows-specific defaults in helper scripts