PsAgentAI/README.md

PsAgentAI - Personal Conversational AI Agent

A Telegram-based conversational AI agent that acts as a personal companion. It maintains long-term memory through user/agent profiles, manages daily routines, supports file uploads/workspace editing, performs web searches, analyzes images, and sends proactive messages based on configured schedules.

Key Features

• Long-term memory: User and agent profiles with auto-enrichment from conversations
• Daily routine management: Schedule activities, meals, work/study times
• File workspace: Create, edit, list and download files via natural language
• Web search: Automatic or on-demand search for up-to-date information with hallucination validation
• Anti-hallucination: Post-search validation ensures responses cite sources and don't invent facts
• Vision: Image analysis with configurable vision models
• Voice: Voice message transcription and response
• Proactive messaging: Scheduled automatic messages based on daily routine
• Multi-provider AI: OpenRouter, StepFun, QwenCloud, and llama.cpp (local)
• System auto-improvement: AI-driven suggestions to evolve the agent behavior

Project Structure

app/
├── psagentai_agent.py          # Main agent code (~5000 lines)
├── iniciar.sh                  # Setup and run script
├── requirements.txt            # Python dependencies
├── .env                        # Local settings (do not commit)
├── user_profile.json           # User profile (auto-created)
├── agent_profile.json          # Agent profile (auto-created)
├── uploads_metadata.json       # Uploaded files metadata (auto-created)
├── config.json                 # Schedule configuration (auto-created)
├── system_improvements.json    # Auto-improvement history (auto-created)
├── contexts/                   # Conversation history by date
│   └── YYYY-MM-DD.json
├── workspace/                  # Created and edited files
│   └── projects/
├── README.md
├── DEPLOY.md
├── RULES.md
└── LICENSE

Prerequisites

• Python 3.9+
• Telegram account with a bot created via @BotFather
• At least one supported AI API key (OpenRouter, StepFun, or QwenCloud)

Configuration

1. Copy .env from the example or create it manually:

cp .env.example .env   # if .env.example exists
nano .env

2. Required variables:

Variable	Required	Description
TELEGRAM_BOT_TOKEN	Yes	Token from @BotFather
TELEGRAM_CHAT_ID	Yes	Your Telegram chat ID
AI_PROVIDER	Yes	openrouter, stepfun, qwencloud or llamacpp
DEFAULT_MODEL	Yes	Model identifier for the chosen provider
OPENROUTER_API_KEY	Conditional	Required if using OpenRouter
STEPFUN_API_KEY	Conditional	Required if using StepFun
QWENCLOUD_API_KEY	Conditional	Required if using QwenCloud

3. Optional tuning:

Variable	Default	Description
MIN_INTERVAL_MINUTES	3	Minimum minutes between proactive messages
MAX_INTERVAL_MINUTES	30	Maximum minutes between proactive messages
MIN_MESSAGE_LINES	3	Minimum lines per agent response
MAX_HISTORY_LENGTH	50	Max messages kept in context
UPLOAD_CONTEXT_MAX_CHARS	8000	Max chars from uploads sent to AI (0 = unlimited)
WEB_SEARCH_ENABLED	true	Enable automatic web search
WEB_SEARCH_MAX_RESULTS	5	Max search results returned
VISION_MODEL	meta-llama/llama-4-maverick-17b-128b-instruct	Model for image analysis
VISION_PROVIDER	auto	Provider for vision model
AUTO_ENRICH_EVERY	2	Update profiles every N messages (0 = disabled)
AUTO_IMPROVE_EVERY	20	Run auto-improvement every N messages (0 = disabled)

Installation

cd app
chmod +x iniciar.sh
./iniciar.sh

The setup script will:

1. Create a Python virtual environment (venv/)
2. Upgrade pip
3. Install dependencies from requirements.txt
4. Validate .env configuration
5. Start the agent

Running

# From the app directory:
python3 psagentai_agent.py

# Or use the setup script:
./iniciar.sh

Available Commands

Core

• /start — Starts or restarts the conversation and onboarding if needed
• /help — Displays quick command reference
• /manual — Full user manual with examples and tips
• /about — System information, version, author and license

Profile

• /profile — Displays your profile and agent summary
• /editprofile — Edit your profile fields interactively
• /addtouserprofile <text> — Add information to your profile
• /agentprofile — Displays the full agent profile
• /editagentprofile — Edit agent profile fields interactively
• /configagentprofile — Configure agent profile interactively (name, personality, traits, notes)
• /addtoagentprofile <text> — Add a note/characteristic to the agent profile
• /onboarding — Re-run your profile onboarding

AI Configuration

• /viewai — Shows current AI provider and model
• /configai — Configure AI provider and model interactively with buttons
• /viewvision — Shows current vision provider and model
• /configvision — Configure vision model interactively with buttons
• /updatesystem — Force analysis and application of auto improvements

Files and Documents

• /uploadfile — Instructions for sending files (.pdf, .txt, .docx, .png, .jpg)
• /listfiles — List all uploaded and created files
• /download <name> — Download a workspace file by name

You can also send files directly in the chat. The agent will read text-based files and images automatically.

Workspace Editing

You can ask the agent to create or edit files in workspace/:

Create:

• create a python script to calculate fibonacci
• develop a web project with html css and js
• generate a document about home automation

Edit:

• edit the file test.txt and add line 4
• modify the file hello.py to print hello world
• in the file test.txt replace Line 2 with Line 2 edited

Daily Routine and Schedule

• /schedule — Set days and times for automatic messages
• /viewschedule — View current schedule
• /dailyroutine — Manage your daily routine (wake up, meals, work/study, sleep)
• /viewdailyroutine — View current daily routine
• /addactivity — Add a new activity to your routine
• /editactivity — Edit an existing activity
• /deleteactivity — Delete an activity

Management

• /newconfig — Reset everything and reconfigure from scratch
• /reset — Reset only user and agent profiles
• /clear — Remove all data (profiles, contexts, chat_id)
• /removetopic <topic> — Remove all content related to a topic from the system
• /cancel — Cancel an ongoing operation

Utilities

• /debug — Shows system debug information
• /reload — Reload .env settings without restarting
• /timezone — Shows the server timezone (read-only)

Natural Language Profile Updates

During conversation, you can update profiles using phrases:

User profile:

• Include this in my profile: ...
• Note in my profile: ...
• Add to my profile: ...
• Save in my profile: ...

Agent profile:

• Include this in the agent profile: ...
• Note in the agent profile: ...

How It Works

1. Onboarding: When you first start, the agent asks questions to build your profile (name, age, gender, location, interests, personality, etc.)
2. Context: Every message is saved to a daily context file (contexts/YYYY-MM-DD.json)
3. Profiles: User and agent profiles are persisted as JSON and enriched automatically based on conversations
4. AI Calls: The agent uses the configured provider/model to generate responses with full context
5. Proactive Messages: Based on your schedule and routine, the agent may initiate conversations
6. Web Search: When enabled, the agent searches the web for questions requiring current information
7. Vision: Images are analyzed using the configured vision model
8. Auto-improvement: The system periodically analyzes conversations and suggests improvements

File Upload and Analysis

Supported formats:

• Documents: .pdf, .txt, .docx
• Images: .png, .jpg, .jpeg

When you upload a file:

1. It's saved to workspace/ or uploads/
2. Text is extracted and stored in uploads_metadata.json
3. Images are analyzed automatically
4. You can ask questions about the file content

Workspace Editing

The agent can create and edit files in workspace/ using AI. Files are organized in subdirectories based on the request type.

To edit an existing file:

• Use /listfiles to see available files
• Use /download <name> to download a file
• Ask the agent to edit by name or partial name

Conversation Context

• Contexts are stored in contexts/YYYY-MM-DD.json
• Old messages are automatically cleaned when limits are exceeded
• The agent references recent context to maintain coherent conversations

Scheduling

The agent sends proactive messages only within the configured schedule:

• Configure days of the week and time range with /schedule
• Messages are sent at random intervals within the configured window
• The agent always uses server time

Security Notes

• Never commit .env to version control
• Restrict .env permissions: chmod 600 .env
• Sensitive data (emails, phones) is preserved but not exposed in logs
• File paths are validated to prevent traversal attacks

Backups

Regularly back up these files:

• user_profile.json
• agent_profile.json
• system_improvements.json
• uploads_metadata.json
• config.json
• contexts/ folder
• workspace/ folder

Example backup:

tar czf /root/backups/psagentai-$(date +%F).tar.gz -C /opt/psagentai/app user_profile.json agent_profile.json system_improvements.json uploads_metadata.json config.json contexts workspace

Troubleshooting

• Bot not responding: Ensure /start has been sent once in the Telegram chat
• AI errors: Check API keys and provider configuration with /viewai
• Voice not working: Ensure ffmpeg is installed
• Image analysis not working: Check vision configuration with /viewvision

Development

See RULES.md for development standards, code conventions, and contribution guidelines.

License

Proprietary for Syspanel.com.br. See LICENSE file.