Repository Guidelines

Project Structure & Module Organization

The root repository is the Python narrative engine. Use cli/ for the public CLI, core/ for pipeline, runtime, reporting, and project logic, and scripts/ for smoke tests, TUIs, and automation entrypoints. Unit tests live in tests/. Prompt templates are versioned in prompts/. Automation state, reports, and manifests live under automation/. Long-form documentation and runbooks live in docs/ and docs/runbooks/. The macOS Studio app is a separate Swift package in app_AI-novel-engine/ with its own Sources/ and Tests/.

Build, Test, and Development Commands

Run the main Python suite with make test or python3 -m unittest discover -s tests -v. Use make healthcheck before runtime-dependent work to verify local services on :8100, :8201, :8091, and :11434. Launch a representative generation smoke test with bash scripts/smoke_local_generation.sh --base-url http://127.0.0.1:8100 --model "apple-coreml:qwen3.5-4b-onnx-q4f16" --approve. Drive automation with python3 scripts/run_next_lots.py --lot full or make lot-full. For the Studio app, run DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer swift test inside app_AI-novel-engine/.

Coding Style & Naming Conventions

Follow existing style rather than introducing a new formatter. Python uses 4-space indentation, type hints, dataclasses where appropriate, snake_case for functions/modules, and PascalCase for classes. Keep CLI and runtime constants explicit and environment-variable names uppercase, for example ANE_BASE_URL. Swift code in app_AI-novel-engine/ follows standard Swift naming: PascalCase types, camelCase members.

Testing Guidelines

Add Python tests in tests/test_*.py and group cases in unittest.TestCase classes named *Tests. Prefer deterministic unit tests with mocks over live runtime calls. When touching automation or tracking, cover both file outputs and state transitions. If you change the Swift app, add or update SwiftPM tests in app_AI-novel-engine/Tests/.

Commit & Pull Request Guidelines

Recent history favors concise Conventional Commit subjects such as feat(pipeline): ..., fix(lots): ..., and chore(gen): .... Keep commits scoped to one concern. PRs should explain the affected workflow, list verification commands, link any relevant issue or dated doc, and include screenshots when app_AI-novel-engine/ UI changes.

Configuration & Generated Content

Do not commit secrets. Local runtime setup relies on ANE_PROVIDER, ANE_BASE_URL, ANE_MODEL, ANE_API_KEY, and optional OPENAI_API_KEY. Do not hand-edit sections wrapped in AUTO-SYNC markers; regenerate them through the supported scripts.

2.7 KiB Raw Permalink Blame History