Skip to content

AGENTS.md

Latest commit

 

History

History
59 lines (51 loc) · 4.44 KB

AGENTS.md

File metadata and controls

59 lines (51 loc) · 4.44 KB

General Instructions

  • This is a production-grade Python package using uv as the package and project manager. You must always follow best open-source Python practices.
  • Shortcuts are not appropriate. When in doubt, you must work with the user for guidance.
  • Any documentation you write, including in the README.md, should be clear, concise, and accurate like the official documentation of other production-grade Python packages.
  • Make sure any comments in code are necessary. A necessary comment captures intent that cannot be encoded in names, types, or structure. Comments should be reserved for the "why", only used to record rationale, trade-offs, links to specs/papers, or non-obvious domain insights. They should add signal that code cannot.
  • The current code in the package should be treated as an example of high quality code. Make sure to follow its style and tackle issues in similar ways where appropriate.
  • Do not run the e2e/integration tests automatically unless asked since they take a while.
  • Don't generate characters that a user could not type on a standard keyboard like fancy arrows.
  • Anything is possible. Do not blame external factors after something doesn't work on the first try. Instead, investigate and test assumptions through debugging through first principles.
  • When writing documentation
    • Keep it very concise
    • No emojis or em dashes.
    • Documentation should be written exactly like it is for production-grade, polished, open-source Python packages.

Python Development Instructions

  • ty by Astral is used for type checking. Always add appropriate type hints such that the code would pass ty's type check.
  • Follow the Google Python Style Guide.
  • After each code change, checks are automatically run. Fix any issues that arise.
  • IMPORTANT: The checks will remove any unused imports after you make an edit to a file. So if you need to use a new import, be sure to use it FIRST (or do your edits at the same time) or else it will be automatically removed. DO NOT use local imports to get around this.
  • At this stage of the project, NEVER add imports to init.py files. Leave them empty unless absolutely necessary.
  • Always prefer pathlib for dealing with files. Use Path.open instead of open.
  • When using pathlib, always Use .parents[i] syntax to go up directories instead of using .parent multiple times.
  • When writing tests, use pytest and pytest-asyncio.
  • Prefer using loguru for logging instead of the built-in logging module. Do not add logging unless requested.
  • NEVER use # type: ignore. It is better to leave the issue and have the user work with you to fix it.
  • Don't put types in quotes unless it is absolutely necessary to avoid circular imports and forward references.
  • When constructing long strings like prompts for LLMs, use python-liquid's render function:
from liquid import render

print(render("Hello, {{ you }}!", you="World"))
# Hello, World!
  • To learn about how packages work, you should read from the relevant source code. This is especially important when determining which types to use.
    • interop-router: Start at .venv/lib/python3.11/site-packages/interop_router/router.py and .venv/lib/python3.11/site-packages/interop_router/types.py
    • openai: Key files stem from .venv/lib/python3.11/site-packages/openai/resources and .venv/lib/python3.11/site-packages/openai/types
    • anthropic: Key files stem from .venv/lib/python3.11/site-packages/anthropic/resources/messages/messages.py
  • Do not manually run checks like uv run ruff format or uv run pytest. They will either be run automatically after code changes or user triggered since they may take a while.

Dependency Context

  • For libraries that are new or change frequently, you must refer to their official documentation or source code.
  • There is a select set of repos cloned that constitute the dependencies for this project at ai_working. You must explore it directly when needed. It can be updated through the Claude command /setup-reference-repos in this project.
    • interop-router
    • openai-python
    • anthropic-sdk-python
    • python-genai - Google Gen AI SDK
    • crawl4ai
  • When looking for something specific that might take a while, use a sub-agent to find it. Tell the sub-agent return the location (paths) of what is found so it can be referenced easily later.
  • To figure out how uv works, start by using uv --help.

Key Files

@README.md

@pyproject.toml

@src/agent_core/_types.py

@docs/DEVELOPMENT.md