Souldroid-Chat/AGENTS.md

AGENTS.md

Agent guidance for this repository (Soul Droid Chat).

Quick Start for New Agents

1. Read game/script.rpy, game/screens.rpy, and game/llm_ren.py to understand flow and LLM integration.
2. Run "/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" lint before making changes.
3. Make small, focused edits that preserve Ren'Py ids and the EMOTION:<value> response contract.
4. Validate with compile and test (test <testcase_or_suite_name> for a single case while iterating).
5. Avoid committing generated artifacts/logs (*.rpyc, game/cache/, log.txt, errors.txt, traceback.txt) or secrets.
6. In your handoff, include what changed, why, and exact validation commands run.

Project Snapshot

• Engine: Ren'Py 8.5.x project with script files in game/*.rpy.
• Python support code is embedded in Ren'Py files and game/*_ren.py.
• Runtime dependency: LM Studio server (default http://localhost:1234).
• No dedicated tests/ directory was found; use Ren'Py lint and test.

Repository Layout

• game/script.rpy: main dialogue/game flow loop.
• game/screens.rpy: UI screens, preferences, and menus.
• game/options.rpy: Ren'Py/build/runtime config and defaults.
• game/llm_ren.py: LLM call logic, parsing, and sanitizing.
• game/constants_ren.py: emotion synonym table.
• project.json, android.json: distribution/build settings.

Tooling and Environment

• Expected Ren'Py launcher script: /home/micost/renpy-8.5.2-sdk/renpy.sh.
• CLI usage pattern:
  • "/home/micost/renpy-8.5.2-sdk/renpy.sh" "<repo-path>" <command> [args]
• Python in environment is available (python3), but gameplay validation should use Ren'Py commands.

Build, Lint, and Test Commands

Run all commands from repository root: /home/micost/Documentos/Renpy Projects/Soul Droid Chat

Quick checks (most common)

• Lint project:
  • "/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" lint
• Run game locally:
  • "/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" run
• Compile scripts/python cache:
  • "/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" compile

Test execution (Ren'Py test runner)

• Run default/global test suite:
  • "/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" test
• Run a single test suite or testcase (important):
  • "/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" test <testcase_or_suite_name>
• Show detailed test report:
  • "/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" test --report-detailed
• Run all testcases even if disabled:
  • "/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" test --enable-all

Distribution/build packaging

• Create distributions (launcher command):
  • "/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" distribute
• Android build exists as a Ren'Py command (if SDK/keystore configured):
  • "/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" android_build

Suggested Validation Sequence for Agents

1. lint
2. compile
3. test (or test <single_case> when iterating)
4. run for a manual smoke check on the edited flow/screen

If a command fails, include the failing command and key error excerpt in your report.

Code Style Guidelines

General principles

• Match existing Ren'Py and Python style in nearby files.
• Prefer small, focused changes; avoid unrelated refactors.
• Keep user-facing narrative tone and Anita persona constraints intact.
• Preserve ASCII-oriented output behavior where current code expects it.

Ren'Py script/style conventions (.rpy)

• Use 4-space indentation; never tabs.
• Keep labels/screen names snake_case (label start, screen quick_menu).
• Keep style declarations grouped and readable (existing file order is a good template).
• For dialogue flow, keep Python blocks short; move reusable logic to *_ren.py.
• Use explicit keyword args when clarity helps (prompt =, fadeout, fadein).
• Do not rename core ids required by Ren'Py ("window", "what", "who", "input").

Python conventions (*_ren.py and embedded init python)

• Imports:
  • Standard library first (re).
  • Ren'Py modules (renpy, persistent).
  • Local imports last (from .constants_ren import SYNONYMS).
• Naming:
  • Functions/variables: snake_case.
  • Constants: UPPER_SNAKE_CASE (EMOTIONS, SYSTEM_PROMPT).
  • Keep names descriptive (parse_emotion, sanitize_speech, fetch_llm).
• Types:
  • Add type hints on new/edited Python functions when practical.
  • Keep return types accurate (for list-returning functions, annotate accordingly).
• Formatting:
  • Follow PEP 8 basics for spacing, line breaks, and readability.
  • Keep multiline literals and dicts formatted consistently with existing file style.

Error handling and resilience

• Wrap external boundary calls (network/LM Studio) with try/except.
• Return safe fallback values that keep game loop stable.
• Error messages should be concise and actionable for debugging.
• Avoid swallowing exceptions silently; at minimum return or log context.
• Preserve conversation continuity fields when present (last_response_id).

LLM integration constraints

• Keep SYSTEM_PROMPT format guarantees consistent unless intentionally changing behavior.
• Maintain EMOTION:<value> parsing contract used by dialogue rendering.
• If you add emotions, update both:
  • EMOTIONS in game/llm_ren.py
  • SYNONYMS in game/constants_ren.py
• Keep speech sanitization aligned with UI/rendering constraints.

UI/screens changes

• Reuse existing gui.* variables and style helpers where possible.
• Keep mobile/small variant handling (renpy.variant("small")) intact.
• Prefer extending existing screens over introducing parallel duplicate screens.
• For settings UI, follow patterns already used in preferences screen.

Agent Working Rules

• Before edits:
  • Read related files fully (at least the touched blocks and nearby context).
  • Check for existing patterns and follow them.
• During edits:
  • Do not include secrets or API keys in committed files.
  • Do not commit generated caches/logs (*.rpyc, log.txt, errors.txt, traceback.txt).
• After edits:
  • Run relevant validation commands from the section above.
  • Summarize what changed, why, and what was validated.

Git and Change Scope

• Keep commits scoped to the requested task.
• Avoid touching binary assets unless the task explicitly requires it.
• If a keystore or credential-like file is changed, call it out explicitly.
• Do not rewrite history unless explicitly requested.

Cursor/Copilot Rules Status

• No repository-specific Cursor rules were found:
  • .cursor/rules/ not present.
  • .cursorrules not present.
• No repository-specific Copilot instruction file found:
  • .github/copilot-instructions.md not present.

If any of the above files are added later, treat them as higher-priority constraints and update this document.