marcocosta10000
fd136db535
Introduce a complete `.env.example` covering Telegram, AI provider, proactive messaging, web search, and vision settings so new users can bootstrap configuration without reading the source. Rework README.md with a feature list, project structure, and variable reference tables; restructure DEPLOY.md with a table of contents, prerequisites, and env var tables; update RULES.md to declare English as the interface and documentation language and to document the `iniciar.sh` entry script. Also add docstrings to schedule and web search helpers and rename `schedule_data` to `schedule_answers` for consistency with the other wizard state variables.
291 lines
9.8 KiB
Markdown
291 lines
9.8 KiB
Markdown
# 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`
|
|
- **Entry script:** `iniciar.sh`
|
|
- **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: English.
|
|
- Agent replies: English.
|
|
- Logs and code: technical English for variable/function names; English for user-facing messages.
|
|
- Documentation: English.
|
|
|
|
---
|
|
|
|
## 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*
|