valuecell AGENTS.md

Guidelines

Python Programming

Python Environment

• Package manager: uv
• Virtual environment: ./python/.venv
• Testing command: uv run pytest

Imports

• Avoid inline imports unless required to break a circular dependency.
• If you import more than three names from a single module, prefer qualified imports:
  • Prefer: import pathlib; pathlib.Path, pathlib.PurePath
  • Avoid: from pathlib import Path, PurePath, PurePosixPath, ...
• Postpone changes to __init__ and __all__ until APIs stabilize.
• Use TYPE_CHECKING for imports only needed for type hints.

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from mypkg.schemas import AgentConfig

Runtime Checks

• Avoid excessive use of getattr, hasattr, and runtime type checks.
• If an object is a pydantic BaseModel, prefer using its validated attributes and type annotations instead of probing attributes at runtime.
• Rely on pydantic validation, model validators, and type hints; prefer TypedDict or Protocol for structural typing when appropriate.
• When runtime checks are necessary, make them explicit, minimal, and well-documented so the reason for the guard is clear.

Async-First Design

• Prefer asynchronous APIs for I/O-bound work.
• Use asyncio or anyio; for HTTP, prefer httpx (async client).
• Ensure clear async boundaries: public APIs and I/O paths should be async.
• Provide minimal sync adapters only when needed, and document them.

import asyncio
from loguru import logger
import httpx

async def fetch_agent_state(url: str, timeout_s: float) -> dict:
    """Fetch agent state from a remote endpoint."""
    async with httpx.AsyncClient(timeout=timeout_s) as client:
        resp = await client.get(url)
        resp.raise_for_status()
        data = resp.json()
        logger.info("Fetched state from {url}", url=url)
        return data

def fetch_agent_state_sync(url: str, timeout_s: float) -> dict:
    """Synchronous adapter. Prefer the async variant."""
    return asyncio.run(fetch_agent_state(url, timeout_s))