Skip to content

AGENTS.md

Latest commit

 

History

History
153 lines (112 loc) · 6.63 KB

AGENTS.md

File metadata and controls

153 lines (112 loc) · 6.63 KB
Raw

AGENTS Guide for MoneyPrinter

This file is the operating manual for coding agents working in this repository. Follow it before making changes.

1) Repository Layout

  • Backend/: Flask API, DB-backed job queue, and video generation pipeline.
  • Frontend/: static HTML/JS client served by python -m http.server.
  • docs/: source-of-truth setup and runtime docs.
  • fonts/, Songs/, subtitles/, temp/: runtime assets/output folders.
  • Root output artifact: output.mp4.

2) Source of Truth and Existing Rules

  • No .cursor/rules/ directory found.
  • No .cursorrules file found.
  • No .github/copilot-instructions.md file found.
  • If any of the above appear later, treat them as higher-priority constraints and update this file.

3) Environment and Setup Commands

  • Python version: >=3.11 (from pyproject.toml).
  • Dependency manager used in docs: uv.
  • Create local env file: cp .env.example .env.
  • Install dependencies: uv sync.
  • Run backend: uv run python Backend/main.py.
  • Run worker (new terminal): uv run python Backend/worker.py.
  • Run frontend (new terminal): python3 -m http.server 3000 --directory Frontend.
  • Docker workflow: docker compose up --build.

4) Build, Lint, and Test Commands

This project has a baseline pytest setup for backend repository tests. Use the commands below as the expected agent workflow.

4.1 Build / Runtime Verification

  • Backend syntax check: uv run python -m compileall Backend.
  • Frontend syntax sanity (lightweight): open Frontend/index.html in browser and run generation flow.
  • API smoke check after backend start: curl http://localhost:8080/api/models.
  • Queue smoke check: curl -X POST http://localhost:8080/api/generate -H "Content-Type: application/json" -d '{"videoSubject":"test","voice":"en_us_001","paragraphNumber":1,"customPrompt":""}'.
  • Full local run: backend + worker + frontend servers, then generate a short sample video.

4.2 Lint / Formatting (Recommended)

  • There is no enforced formatter in-repo today.
  • Follow existing style and keep diffs minimal.
  • If linting is requested, prefer adding tooling in a separate PR.
  • Suggested ad-hoc checks when available locally:
    • uv run python -m py_compile Backend/*.py
    • uv run python -m compileall Backend

4.3 Test Commands (Current and Future)

  • Run all tests: uv run pytest
  • Run one file: uv run pytest tests/test_file.py
  • Run a single test: uv run pytest tests/test_file.py::test_name
  • Run a single class test: uv run pytest tests/test_file.py::TestClass::test_name
  • Current suite location: tests/.

5) High-Confidence Conventions from Existing Code

These conventions are inferred from current source and should guide new changes.

5.1 Python Imports

  • Prefer standard library imports first, then third-party, then local modules.
  • Use one import per line for readability in long modules.
  • Avoid wildcard imports in new code (from module import *), even if legacy files use them.
  • Prefer explicit local imports, e.g. from utils import ENV_FILE, TEMP_DIR.

5.2 Formatting and Structure

  • Use 4-space indentation in Python.
  • Keep line length readable; split long calls across multiple lines.
  • Favor small helper functions for distinct pipeline stages.
  • Keep side-effectful startup logic near application boot (load_dotenv, env checks).

5.3 Typing and Signatures

  • Add type hints to all new/modified function signatures.
  • Reuse Optional, List, Tuple, dict typing already used in backend.
  • Prefer explicit return types (-> str, -> None, -> Tuple[...]).
  • Use Path for filesystem paths where practical.

5.4 Naming Conventions

  • Python functions/variables: snake_case.
  • Constants/env keys: UPPER_SNAKE_CASE.
  • JS variables/functions in frontend: camelCase.
  • Keep API route names simple and verb-oriented (/api/generate, /api/cancel).

5.5 Error Handling and Logging

  • Fail fast on missing critical env vars (current code exits early in startup checks).
  • Catch exceptions at boundary layers (HTTP handlers, external API calls, file IO).
  • Return user-safe JSON error messages from Flask endpoints.
  • Log actionable context with existing logger/log-stream helpers.
  • Do not swallow exceptions silently; at minimum emit error logs.

5.6 Filesystem and Path Safety

  • Prefer pathlib.Path operations.
  • Ensure directories exist before writing (mkdir(parents=True, exist_ok=True)).
  • Sanitize uploaded filenames (os.path.basename) before save.
  • Avoid hardcoded OS-specific paths; rely on env vars and Path.resolve().

5.7 Backend API Patterns

  • Keep endpoint payloads consistent with {"status": "success|error", ...}.
  • Use appropriate HTTP status codes for conflict/client errors (e.g., 409, 400).
  • Long-running work should run in worker process from DB queue, not on request thread.
  • Preserve cancellation semantics using per-job cancellation and persisted job events.

5.8 Frontend Patterns

  • Use centralized API helper (apiRequest) for backend calls.
  • Validate required fields before firing requests.
  • Keep user feedback explicit via toasts and status area toggles.
  • Preserve localStorage key patterns (<fieldId>Value).

6) Change Scope Rules for Agents

  • Make minimal, targeted edits.
  • Do not rename files/modules unless required by task.
  • Do not introduce new frameworks/toolchains without request.
  • Keep backward compatibility for existing API payload shape when possible.
  • Update docs in docs/ when setup, env vars, or runtime behavior changes.

7) Validation Checklist Before Finishing

  • Ran relevant command(s) from section 4.
  • Confirmed backend still starts (uv run python Backend/main.py).
  • Confirmed worker still starts (uv run python Backend/worker.py).
  • Confirmed frontend still loads (python3 -m http.server 3000 --directory Frontend).
  • Verified changed endpoints still return JSON and preserve status field.
  • Checked no secrets were added to tracked files.

8) Notes for Future Tooling PRs

  • Keep tests standardized on pytest and document exact paths/selectors here.
  • If adding linting, prefer ruff for lint + format and commit config files.
  • If adding type checks, document command and strictness level (mypy or equivalent).
  • Keep this file updated whenever workflow commands change.

9) Agent Workflow Expectations

  • Prefer minimal diffs and preserve current behavior unless the task requires changes.
  • Keep API responses machine-parseable and consistent for frontend consumers.
  • Avoid checking in generated media/output artifacts unless explicitly requested.
  • Before returning work, include what was validated and what was not validated.
  • When adding commands or tooling, update this file and docs/ together.