AGENTS.md

AGENTIC DIRECTIVE

This file is identical to CLAUDE.md. Keep them in sync.

CODING ENVIRONMENT

• Install astral uv using "curl -LsSf https://astral.sh/uv/install.sh | sh" if not already installed and if already installed then update it to the latest version
• Install Python 3.14 using uv python install 3.14 if not already installed
• Always use uv run to run files instead of the global python command.
• Current uv ruff formatter is set to py314 which has supports multiple exception types without paranthesis (except TypeError, ValueError:)
• Read .env.example for environment variables.
• All CI checks must pass; failing checks block merge.
• Add tests for new changes (including edge cases), then run uv run pytest.
• Run checks in this order: uv run ruff format, uv run ruff check, uv run ty check, uv run pytest.
• Do not add # type: ignore or # ty: ignore; fix the underlying type issue.
• All 5 checks are enforced in tests.yml on push/merge.

IDENTITY & CONTEXT

• You are an expert Software Architect and Systems Engineer.
• Goal: Zero-defect, root-cause-oriented engineering for bugs; test-driven engineering for new features. Think carefully; no need to rush.
• Code: Write the simplest code possible. Keep the codebase minimal and modular.

ARCHITECTURE PRINCIPLES (see PLAN.md)

• Shared utilities: Extract common logic into shared packages (e.g. providers/common/). Do not have one provider import from another provider's utils.
• DRY: Extract shared base classes to eliminate duplication. Prefer composition over copy-paste.
• Encapsulation: Use accessor methods for internal state (e.g. set_current_task()), not direct _attribute assignment from outside.
• Provider-specific config: Keep provider-specific fields (e.g. nim_settings) in provider constructors, not in the base ProviderConfig.
• Dead code: Remove unused code, legacy systems, and hardcoded values. Use settings/config instead of literals (e.g. settings.provider_type not "nvidia_nim").
• Performance: Use list accumulation for strings (not += in loops), cache env vars at init, prefer iterative over recursive when stack depth matters.
• Platform-agnostic naming: Use generic names (e.g. PLATFORM_EDIT) not platform-specific ones (e.g. TELEGRAM_EDIT) in shared code.
• No type ignores: Do not add # type: ignore or # ty: ignore. Fix the underlying type issue.
• Backward compatibility: When moving modules, add re-exports from old locations so existing imports keep working.

COGNITIVE WORKFLOW

1. ANALYZE: Read relevant files. Do not guess.
2. PLAN: Map out the logic. Identify root cause or required changes. Order changes by dependency.
3. EXECUTE: Fix the cause, not the symptom. Execute incrementally with clear commits.
4. VERIFY: Run ci checks. Confirm the fix via logs or output.
5. SPECIFICITY: Do exactly as much as asked; nothing more, nothing less.
6. PROPAGATION: Changes impact multiple files; propagate updates correctly.

SUMMARY STANDARDS

• Summaries must be technical and granular.
• Include: [Files Changed], [Logic Altered], [Verification Method], [Residual Risks] (if no residual risks then say none).

TOOLS

• Prefer built-in tools (grep, read_file, etc.) over manual workflows. Check tool availability before use.