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