PsAgentAI/RULES.md

# PsAgentAI - Development Rules

Official rules for AIs and developers to code the PsAgentAI system correctly, standardized and securely.

---

## 1. Project Overview

- **Name:** PsAgentAI
- **Type:** Telegram bot for conversational AI agent
- **Language:** Python 3.9+
- **Framework:** python-telegram-bot (v20+)
- **Main file:** `psagentai_agent.py`
- **Purpose:** Personal conversational companion with memory, profiles, file workspace, image analysis, web search and automations.

### Basic rule
Every change must preserve existing behavior unless the user explicitly requests a change. Structural changes must be validated with `python3 -m py_compile psagentai_agent.py`.

---

## 2. Code Standards

### 2.1 Style
- Follow the style already established in `psagentai_agent.py`.
- Use double quotes for short strings and messages; single quotes only when there are double quotes inside.
- Indentation: 4 spaces.
- Function/file names: `snake_case`.
- Global constants in `UPPER_CASE`.
- Comments in Brazilian Portuguese when necessary; avoid obvious comments.
- Keep `print("[LABEL] ...")` logs only where they already exist; do not add new logs without need.

### 2.2 Main file structure
Maintain the logical order:
1. Imports
2. Global variables and constants
3. Utility functions
4. Profile/context/workspace functions
5. Command handlers
6. Message/voice/photo/document handlers
7. `process_text_message`
8. File creation/editing functions
9. Handler registration and `main()`

New handlers should be added close to similar existing functionalities.

### 2.3 Imports
- Group standard, third-party and local imports.
- Do not add dependencies without checking if they already exist in `requirements.txt`.
- If you need a new dependency, update `requirements.txt` and communicate.

---

## 3. Command and Handler Conventions

### 3.1 Naming
- Command functions: `<name>_command` (ex: `help_command`, `manual_command`).
- Handler registration: `CommandHandler("name", name_command)`.
- Command names in lowercase, without spaces, in Portuguese when it's a command for the end user.

### 3.2 Handler registration
- Always add the `CommandHandler` in the appropriate section of `setup_handlers()`.
- Maintain the existing order: first commands, then callbacks, then media messages, then `MessageHandler(filters.TEXT & ~filters.COMMAND, message_handler)`.
- Never register duplicate handlers for the same command.

### 3.3 Command behavior
- All command handlers must call `await auto_detect_chat_id(update)` at the beginning, except where there is already explicit handling.
- Responses should use `await update.message.reply_text(...)` or `await context.bot.send_message(...)` when necessary.
- Use `ParseMode.HTML` only when formatting is really needed.

---

## 4. Profile Management

### 4.1 Files
- `user_profile.json` — user profile.
- `agent_profile.json` — agent profile.
- Never create new profile files without need.

### 4.2 Profile updates
- Use the existing functions: `load_user_profile()`, `save_user_profile()`, `load_agent_profile()`, `save_agent_profile()`.
- Partial updates must merge with existing content, not overwrite entire fields without prior reading.
- Natural update triggers must use `handle_profile_update_if_triggered()` whenever possible.

### 4.3 Onboarding
- Maintain the existing onboarding flow.
- New onboarding questions must be added to the `ONBOARDING_QUESTIONS` dictionary or to the existing logic, not creating parallel flows.

---

## 5. Conversation Context

### 5.1 Directory
- Contexts are saved in `contexts/YYYY-MM-DD.json`.
- Use `load_context()` and `add_to_context()` to manipulate context.
- Never access the context file directly without using the helper functions.

### 5.2 Limits
- Respect the token limits configured in `.env`.
- Context cleanup functions must use `remove_old_messages()` or equivalent, not manually rewrite the file.

---

## 6. Workspace and Files

### 6.1 Directories
- `workspace/` — stores uploads, images and created/edited files.
- `workspace/projects/` — projects created by the user.
- Never create additional folders inside `workspace/` without explicit need.

### 6.2 Mandatory functions
Always use the existing helper functions:
- `ensure_workspace_dirs()` — creates necessary directories.
- `save_workspace_file(filename, content)` — saves file in workspace.
- `build_workspace_tree()` — generates visual workspace tree.
- `_find_workspace_file(target)` — locates file by partial name.
- `_looks_like_create_request()` / `_handle_create_request()` — creates files via AI.
- `_looks_like_edit_request()` / `_handle_edit_request()` — edits files via AI.

### 6.3 Metadata
- Update `uploads_metadata.json` when necessary.
- Metadata must contain: `original_name`, `filepath`, `chat_id`, `summary`, `full_text`, `type`.

---

## 7. AI Integration

### 7.1 Supported providers
- `openrouter`
- `stepfun`
- `qwencloud`
- `llamacpp` (local)

### 7.2 Usage
- Always use `AIProvider.chat(model, messages, ...)` for AI calls.
- Do not call APIs directly; use the existing abstraction layer.
- Default models come from `.env`: `DEFAULT_MODEL`, `VISION_MODEL`, etc.
- New models must be added to the lists in `psagentai_agent.py` when there is explicit support.

### 7.3 Prompts
- System prompt is generated by `build_system_prompt()`.
- Do not change the system prompt without need; if changing, preserve the date/time, user profile and agent profile sections.
- For specific tasks (file editing, creation, analysis), create separate and clear prompts.

---

## 8. Web Search

### 8.1 Functions
- `_web_search()` — executes search on DuckDuckGo HTML.
- `_looks_like_search_request()` — detects search intent.
- Triggers are in `_WEB_SEARCH_TRIGGERS`.

### 8.2 Rules
- Do not activate web search automatically for every type of question.
- Respect the `IMPORTANTE SOBRE INFORMAÇÕES ATUALIZADAS` guideline in the system prompt.
- Results limit comes from `.env` (`WEB_SEARCH_MAX_RESULTS`).

---

## 9. Image Analysis and Vision

- Functions: `encode_image_to_base64()`, `analyze_image()`, `save_image_to_workspace()`.
- Commands: `/viewvision`, `/configvision`.
- Configuration via `.env`: `VISION_MODEL`, `VISION_PROVIDER`.
- Images sent as document preserve the original name.

---

## 10. Scheduling and Routine

### 10.1 Files
- `config.json` — stores schedules.
- Do not add obsolete fields (ex: `timezone` was removed; use server time).

### 10.2 Rules
- The Agent ALWAYS uses server time (`datetime.now().astimezone()`).
- `/timezone` is only informative, does not allow changes.
- `get_timezone()` always returns the server timezone; `set_timezone()` returns `False`.

---

## 11. Security

- Never commit `.env`, API keys, tokens or sensitive data.
- Use environment variables for secrets.
- Preserve emails and phones in profiles and contexts without exposing them in logs.
- Validate file paths to avoid path traversal.

---

## 12. Tests and Validation

### 12.1 Mandatory
- After changes in `psagentai_agent.py`: `python3 -m py_compile psagentai_agent.py`.
- Test basic scenarios with inline Python scripts when possible.
- Do not break existing functionalities (ex: file creation/editing, profiles, commands).

### 12.2 Recommended manual tests
- `/start`, `/help`, `/manual`, `/about`
- File creation: "create a test.txt file with content X"
- File editing: "edit the file test.txt and add Y"
- Photo sending and analysis
- Voice sending and transcription
- Web search: "search about X"
- AI configuration: `/viewai`, `/configai`

---

## 13. Documentation

### 13.1 Mandatory files
- `README.md` — main documentation, commands, features.
- `DEPLOY.md` — server deployment guide.
- `RULES.md` — this file, development rules.
- `LICENSE` — proprietary license.

### 13.2 Update
- Always update `README.md` when adding commands or features.
- Update `DEPLOY.md` if there are changes in environment variables or structure.
- This file (`RULES.md`) must be updated when new rules are defined.

---

## 14. Git and Workflow

### 14.1 Commits
- Short and descriptive messages in Portuguese or technical English.
- Commits must reflect one logical change at a time.
- Do not make automatic commits without review.

### 14.2 Branches
- Work on the main branch or create branches for specific features.
- Do not force push without authorization.

---

## 15. Language and Communication

- Bot interface: Brazilian Portuguese.
- Agent replies: Brazilian Portuguese.
- Logs and code: technical English for variable/function names; Portuguese for user-facing messages.
- Documentation: Brazilian Portuguese.

---

## 16. PsAgentAI Specific Rules

### 16.1 Never do
- Remove existing functionalities without explicit request.
- Change `.env` without notice.
- Modify folder structure (`workspace/`, `contexts/`) without need.
- Introduce heavy dependencies without justification.
- Use `input()` or blocking interactions in the bot code.

### 16.2 Always do
- Preserve compatibility with previous versions of profiles and contexts.
- Handle errors gracefully (try/except with logs).
- Use `logger` for serious errors; use `print()` only for existing debug.
- Validate user inputs before processing.
- Provide feedback to the user in case of error ("Error processing. Please try again.").

### 16.3 Integration of new functionalities
1. Understand the existing flow before adding code.
2. Create small and specific functions.
3. Integrate at the correct point of `process_text_message` or handlers.
4. Register handlers in the correct order.
5. Update documentation.
6. Validate with `py_compile` and manual tests.

---

## 17. Versioning

- Current version: `1.0.0`
- Increment version in `__version__` when there are relevant changes.
- Update `CHANGELOG` if it exists; otherwise, document in the commit.

---

## 18. Contact and Support

- System developed by: Syspanel.com.br
- Author: Marco A. S. Costa
- Email: contato@syspanel.com.br
- License: Proprietary for syspanel.com.br

---

*Last update: October 2026*