AGENTS.md

Agents Notes for Aileen3 Core

Build & runtime

• The production image (HuggingFace Space) is built from Dockerfile in repo root; whenever adding a Python package or new source tree that must be available at runtime, copy it in the Dockerfile and install it (editable is fine).
• Gradio demo runs via python demo/app.py; ensure dependencies are in demo/requirements.txt and installed in the image.
• Python version: 3.11 (see Dockerfile).

MCP server/client

• Local MCP server lives under mcp/; expose entrypoint aileen3_mcp.server. The demo must call it at runtime, make sure the image installs ./mcp (editable) and that PYTHONPATH is not relied on in production.
• The demo health check spawns the MCP server via sys.executable -m aileen3_mcp.server; keep that aligned with the Docker image.

Gradio demo

The Gradio demo demo/app.py is organized akin to a Jupyter notebook: several cells provide explanations and live demonstration of functionality. Adding such a cell shall typically entail adding the code (both cell UI rendering and functionality) to a separate file. A simple example is the health check cell.

Testing / quick checks

• Lightweight check before committing: python3 -m compileall demo mcp/src.

Logging / diagnostics

• Health probes log spawn command, args, PYTHONPATH, and cwd; use Space logs to debug import issues.

When changing dependencies

• Update requirements.txt and pyproject.toml and the Dockerfile install layer together; avoid drift. These files exist on a per-project level (mcp/ and demo/), be sure to update the correct ones.

Style

• Use American English throughout