✕
Skip to content

AGENTS.md

Latest commit

 

History

History
73 lines (58 loc) · 3.55 KB

AGENTS.md

File metadata and controls

73 lines (58 loc) · 3.55 KB
Raw

Agentic Ecology Workspace Guidelines

Environment & Workspace Management

  • Environment Management: This repository is managed exclusively with uv. All dependency resolution and environment setup are handled by uv. The soundfile library is guaranteed to be available in this environment; do not waste steps verifying its installation.
  • Agent Artifacts: You MUST store artifacts (Python scripts, Markdown documents, etc.) in the agent_workspace directory inside the repository's root directory so that the user can inspect your work. Do NOT create or commit any temporary, throwaway, or scratch files anywhere else.
  • Code Execution: The correct and mandatory way to interact with Python scripts or modules is via the uv run python command prefix. This ensures the correct environment and dependencies (such as perch-hoplite) are used. Any code you run MUST be in the form of a script in the agent_workspace directory.
  • Adherence to Skills & Templates: You MUST closely review and adhere to the design patterns, utility functions (e.g., sanitize_float for JSON/JS compatibility), and thread-safety patterns defined in the .agents/skills/ templates. When transitioning from mock templates to real implementations, ensure all template-provided safety guards are fully preserved and applied to live data flows to prevent known edge-case failures (such as NaN serialization or multi-threaded SQLite connection errors).

Technical Gotchas & Rules

1. macOS Dynamic Library Deadlock (TensorFlow & PyArrow)

On macOS, both tensorflow and pyarrow (Apache Arrow) statically link Abseil (absl) but expose their symbols globally. Due to macOS's namespace resolution, if pyarrow is loaded first, tensorflow will bind to incompatible Abseil symbols, causing a compiler deadlock.

  • Rule: Always force import tensorflow as tf at the absolute top of any Python script or entry point that uses JAX or TensorFlow.
  • Rule: Ensure this import precedes any imports of perch_hoplite, pandas, gcsfs, fsspec, or packages that transitively load pyarrow.

1b. Linux PyTorch & TensorFlow Import Conflict (Segmentation Fault)

On Linux, there is a symbol conflict between PyTorch (yolov5) and TensorFlow. If tensorflow is imported first, subsequent imports of yolov5 will segfault.

  • Rule: If a script imports both yolov5 and tensorflow, import yolov5 MUST be placed at the absolute top of the script, preceding import tensorflow as tf.

2. Suppressing Internal SQL Trace Logs

The perch-hoplite database adapter logs every executed query at INFO level, clogging logs.

  • Rule: Implement a targeted logging.Filter to discard only the "Executed SQL statement" entries at your script's entry point:

    import logging
class SQLSuppressFilter(logging.Filter):
  def filter(self, record):
    return "Executed SQL statement" not in record.getMessage()
logging.getLogger("absl").addFilter(SQLSuppressFilter())

3. Skill Authoring Guidelines (for .agents/skills/)

  • Separate Workflow from Reference: Keep SKILL.md focused on high-level workflow steps. Move CLI commands and code references to references/technical_reference.md.
  • Address the Agent: Skill instructions must address the agent directly in the imperative mood.
  • Workspace Sandboxing: Ensure all active scripts, templates, and server processes copy files to the agent_workspace/ directory before execution.