| # 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. |
| |
