marcocosta10000/PsAgentAI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(config): add .env.example and overhaul README, DEPLOY, and RULES documentation

Browse Source 
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.
This commit is contained in:
marcocosta10000
2026-10-26 14:25:47 -03:00
parent 9848120a1a
commit fd136db535
6 changed files with 2588 additions and 187 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.env.example
+106
View File
@@ -0,0 +1,106 @@
# =============================================================================
# PsAgentAI - Environment Configuration Example
# =============================================================================
# Copy this file to .env and fill in your actual values:
# cp .env.example .env
# =============================================================================
# -----------------------------------------------------------------------------
# Telegram Configuration
# -----------------------------------------------------------------------------
# Get your bot token from @BotFather (https://t.me/BotFather)
TELEGRAM_BOT_TOKEN=your_bot_token_here
# Your Telegram chat ID (the bot will send proactive messages to this chat)
TELEGRAM_CHAT_ID=your_chat_id_here
# -----------------------------------------------------------------------------
# AI Provider Configuration
# -----------------------------------------------------------------------------
# Provider: openrouter, stepfun, qwencloud or llamacpp
AI_PROVIDER=openrouter
# Default model identifier (depends on the chosen provider)
DEFAULT_MODEL=poolside/laguna-s-2.1:free
# Comma-separated fallback models if the primary fails
FALLBACK_MODELS=poolside/laguna-s-2.1:free,google/gemini-2.0-flash-lite-preview-02-05:free
# -----------------------------------------------------------------------------
# OpenRouter Configuration (https://openrouter.ai)
# -----------------------------------------------------------------------------
OPENROUTER_API_KEY=your_openrouter_key_here
OPENROUTER_API_URL=https://openrouter.ai/api/v1
# -----------------------------------------------------------------------------
# StepFun Configuration (https://platform.stepfun.com)
# -----------------------------------------------------------------------------
STEPFUN_API_KEY=your_stepfun_key_here
STEPFUN_API_URL=https://api.stepfun.com/v1
# -----------------------------------------------------------------------------
# QwenCloud Configuration (https://dashscope.aliyun.com)
# -----------------------------------------------------------------------------
QWENCLOUD_API_KEY=your_qwencloud_key_here
QWENCLOUD_API_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
# -----------------------------------------------------------------------------
# llama.cpp Configuration (local server)
# -----------------------------------------------------------------------------
# URL of your local llama.cpp server (OpenAI-compatible endpoint)
LLAMA_CPP_API_URL=http://localhost:8080/v1
# -----------------------------------------------------------------------------
# Proactive Messaging
# -----------------------------------------------------------------------------
# Minimum and maximum interval between proactive messages (minutes)
MIN_INTERVAL_MINUTES=3
MAX_INTERVAL_MINUTES=30
# -----------------------------------------------------------------------------
# Context and History
# -----------------------------------------------------------------------------
# Maximum number of messages kept in conversation context
MAX_HISTORY_LENGTH=50
# Maximum characters from uploaded files sent to AI (0 = no truncation)
UPLOAD_CONTEXT_MAX_CHARS=8000
# -----------------------------------------------------------------------------
# Web Search
# -----------------------------------------------------------------------------
# Enable automatic web search when the agent detects an information need
WEB_SEARCH_ENABLED=true
# Maximum number of search results to include in context
WEB_SEARCH_MAX_RESULTS=5
# -----------------------------------------------------------------------------
# Vision / Image Analysis
# -----------------------------------------------------------------------------
# Model used for image analysis
VISION_MODEL=meta-llama/llama-4-maverick-17b-128b-instruct
# Provider for the vision model (leave empty to auto-detect from model)
VISION_PROVIDER=
# -----------------------------------------------------------------------------
# Agent Behavior
# -----------------------------------------------------------------------------
# Minimum number of lines per agent message
MIN_MESSAGE_LINES=3
# Auto-enrich user/agent profiles every N messages (0 = disabled)
AUTO_ENRICH_EVERY=2
# Auto-improve system every N messages (0 = disabled)
AUTO_IMPROVE_ENABLED=true
AUTO_IMPROVE_EVERY=20
# -----------------------------------------------------------------------------
# Persistence
# -----------------------------------------------------------------------------
# File paths for profiles and contexts (relative to app directory)
USER_PROFILE_FILE=user_profile.json
AGENT_PROFILE_FILE=agent_profile.json
CONTEXTS_DIR=contexts
DEPLOY.md
+258 -95
View File
@@ -1,17 +1,38 @@
# PsAgentAI - Server Deployment # PsAgentAI - Server Deployment
Deploy as a systemd service on Debian/Ubuntu to run 24/7 on a VPS. Deploy PsAgentAI as a systemd service on Debian/Ubuntu to run 24/7 on a VPS.
## Table of Contents
1. [Prerequisites](#prerequisites)
2. [Copy Project to Server](#1-copy-project-to-server)
3. [Configure Environment](#2-configure-environment)
4. [Install Dependencies](#3-install-dependencies)
5. [Install systemd Service](#4-install-systemd-service)
6. [Service Management](#5-service-management)
7. [Updates](#6-updates)
8. [Multi-User Deployment](#7-multi-user-deployment)
9. [Environment Variables Reference](#8-environment-variables-reference)
10. [Backups](#9-backups)
11. [Security](#10-security)
--- ---
## Prerequisites on the server ## Prerequisites
A fresh Debian/Ubuntu server with:
- `python3`, `python3-venv`, `python3-pip`
- `git` (if cloning from repository)
- `ffmpeg` (for voice message processing)
- `systemd-journal-remote` (optional, for persistent logs)
```bash ```bash
sudo apt update sudo apt update
sudo apt install -y python3 python3-venv python3-pip git ffmpeg sudo apt install -y python3 python3-venv python3-pip git ffmpeg
``` ```
Enable journal if you want persistent logs (optional): Optional: enable persistent journal logs:
```bash ```bash
sudo apt install -y systemd-journal-remote sudo apt install -y systemd-journal-remote
@@ -19,9 +40,9 @@ sudo apt install -y systemd-journal-remote
--- ---
## 1) Copy the project to the server ## 1) Copy Project to Server
Use git or scp/rsync. Example with git: ### Using git
```bash ```bash
cd /opt cd /opt
@@ -30,77 +51,92 @@ sudo chown -R $USER:$USER /opt/psagentai
cd /opt/psagentai/app cd /opt/psagentai/app
``` ```
Adjust the path in the systemd service to the real directory: ### Using scp/rsync
```bash ```bash
nano psagentai.service # From your local machine:
# change /home/marco/PsAgentAI/app to /opt/psagentai/app scp -r psagentai/ user@server:/opt/psagentai/
``` ```
> The service uses `User=marco` by default. Create the user if it doesn't exist: Adjust paths in the systemd service file to match your actual installation directory.
> ```bash
> sudo useradd -m -s /bin/bash marco || true
> sudo usermod -aG sudo marco
> ```
> Or edit `User=` in the `.service` to an existing user on your VPS.
--- ---
## 2) Configure `.env` ## 2) Configure Environment
```bash ```bash
cp .env.example .env # if example exists # If .env.example exists, copy it:
cp .env.example .env
# Otherwise create .env manually:
nano .env nano .env
``` ```
Fill in the required fields: ### Required settings
- `TELEGRAM_BOT_TOKEN` | Variable | Description |
- `TELEGRAM_CHAT_ID` |---|---|
- `AI_PROVIDER` (`openrouter`, `stepfun`, `qwencloud` or `llamacpp`) | `TELEGRAM_BOT_TOKEN` | Token from @BotFather |
- `DEFAULT_MODEL` | `TELEGRAM_CHAT_ID` | Your Telegram chat ID |
- at least the AI key corresponding to the chosen provider | `AI_PROVIDER` | `openrouter`, `stepfun`, `qwencloud` or `llamacpp` |
| `DEFAULT_MODEL` | Model identifier for the chosen provider |
| `OPENROUTER_API_KEY` or `STEPFUN_API_KEY` or `QWENCLOUD_API_KEY` | At least one AI provider key |
Optionally adjust: ### Optional settings
- `MIN_INTERVAL_MINUTES` / `MAX_INTERVAL_MINUTES` | Variable | Default | Description |
- `MIN_MESSAGE_LINES` |---|---|---|
| `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 message |
| `WEB_SEARCH_ENABLED` | `true` | Enable automatic web search |
| `WEB_SEARCH_MAX_RESULTS` | `5` | Max web search results |
| `VISION_MODEL` | `meta-llama/llama-4-maverick-17b-128b-instruct` | Vision model |
| `VISION_PROVIDER` | auto | Vision provider |
| `AUTO_ENRICH_EVERY` | `2` | Profile auto-enrichment frequency (`0` = disabled) |
| `AUTO_IMPROVE_EVERY` | `20` | Auto-improvement frequency (`0` = disabled) |
| `UPLOAD_CONTEXT_MAX_CHARS` | `8000` | Upload context limit (`0` = unlimited) |
> Important: on Telegram, send `/start` once to the bot before turning on the service, otherwise it won't be able to send starting messages. > **Important**: Before starting the service, send `/start` once to the bot in Telegram. This allows the bot to resolve the chat and send proactive messages later.
--- ---
## 3) Install dependencies ## 3) Install Dependencies
```bash ```bash
# Install system dependency for voice processing
sudo apt install -y ffmpeg sudo apt install -y ffmpeg
```bash # Make setup script executable and run it
chmod +x iniciar.sh chmod +x iniciar.sh
./iniciar.sh ./iniciar.sh
``` ```
This script creates the `venv`, installs dependencies and validates the `.env` variables. The setup script will:
1. Create a Python virtual environment (`venv/`)
2. Upgrade `pip`
3. Install Python dependencies from `requirements.txt`
4. Validate `.env` configuration
5. Start the agent
If the above command doesn't install the expected `ffmpeg` version, also use: If `ffmpeg` was not installed by the system package manager, install it separately:
```bash ```bash
sudo apt install -y ffmpeg sudo apt install -y ffmpeg
``` ```
> Voice recognition uses `SpeechRecognition` + `pydub` + `ffmpeg`. > Voice recognition requires `SpeechRecognition` + `pydub` + `ffmpeg`.
--- ---
## 4) Install the systemd service ## 4) Install systemd Service
Create the service file:
```bash ```bash
# absolute path on your server
sudo nano /etc/systemd/system/psagentai.service sudo nano /etc/systemd/system/psagentai.service
``` ```
Minimum content:
```ini ```ini
[Unit] [Unit]
Description=PsAgentAI Description=PsAgentAI
@@ -109,6 +145,7 @@ After=network.target
[Service] [Service]
Type=simple Type=simple
User=marco User=marco
Group=marco
WorkingDirectory=/opt/psagentai/app WorkingDirectory=/opt/psagentai/app
Environment="PATH=/opt/psagentai/app/venv/bin:/usr/local/bin:/usr/bin:/bin" Environment="PATH=/opt/psagentai/app/venv/bin:/usr/local/bin:/usr/bin:/bin"
ExecStart=/opt/psagentai/app/venv/bin/python3 /opt/psagentai/app/psagentai_agent.py ExecStart=/opt/psagentai/app/venv/bin/python3 /opt/psagentai/app/psagentai_agent.py
@@ -121,7 +158,21 @@ StandardError=journal
WantedBy=multi-user.target WantedBy=multi-user.target
``` ```
Enable and start: Adjust the following to match your setup:
- `User=` and `Group=` — the user that will run the service
- `WorkingDirectory=` — absolute path to the `app/` directory
- `ExecStart=` — absolute path to the Python executable and agent script
Create the service user if needed:
```bash
sudo useradd -m -s /bin/bash marco || true
sudo usermod -aG sudo marco
```
Or change `User=` and `Group=` to an existing user on your VPS.
Reload systemd and enable the service:
```bash ```bash
sudo systemctl daemon-reload sudo systemctl daemon-reload
@@ -131,25 +182,28 @@ sudo systemctl start psagentai
--- ---
## 5) Useful commands ## 5) Service Management
```bash ```bash
# status # Check status
sudo systemctl status psagentai sudo systemctl status psagentai
# real-time logs # View real-time logs
sudo journalctl -u psagentai -f sudo journalctl -u psagentai -f
# restart after update # Stop the service
sudo systemctl stop psagentai
# Restart after changes
sudo systemctl restart psagentai sudo systemctl restart psagentai
# stop # Disable auto-start
sudo systemctl stop psagentai sudo systemctl disable psagentai
``` ```
--- ---
## 6) Future updates ## 6) Updates
```bash ```bash
cd /opt/psagentai/app cd /opt/psagentai/app
@@ -160,80 +214,189 @@ sudo systemctl restart psagentai
--- ---
## 7) Multiple users / VPSs ## 7) Multi-User Deployment
Each system instance is independent by Telegram chat ID. Each PsAgentAI instance is independent by Telegram chat ID. To run multiple instances:
For each new user/VPS: 1. Create a separate bot via [@BotFather](https://t.me/BotFather) (`/newbot`) for each user
2. Copy the project to a separate directory for each instance, e.g.:
- `/opt/psagentai-user1/`
- `/opt/psagentai-user2/`
3. Create a dedicated `.env` for each instance with its own `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`, and AI keys
4. Run `./iniciar.sh` in each directory to set up the environment
5. Create a separate systemd service file for each instance:
1. Create the bot via @BotFather (`/newbot`) and get the token. ```bash
2. Copy the project to a separate directory, for example `/opt/psagentai-user2`. # Example for user2
3. Create your own `.env` with `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID` and your AI keys. sudo nano /etc/systemd/system/psagentai-user2.service
4. Install dependencies with `./iniciar.sh`. ```
5. Create a separate systemd service, ex: `psagentai-user2.service`, pointing to that directory.
6. Enable and start.
Recommended names to avoid conflicts: ```ini
[Unit]
Description=PsAgentAI - User 2
After=network.target
- `/opt/psagentai-user1/`, `/opt/psagentai-user2/` [Service]
- `psagentai-user1.service`, `psagentai-user2.service` Type=simple
User=marco
Group=marco
WorkingDirectory=/opt/psagentai-user2/app
Environment="PATH=/opt/psagentai-user2/app/venv/bin:/usr/local/bin:/usr/bin:/bin"
ExecStart=/opt/psagentai-user2/app/venv/bin/python3 /opt/psagentai-user2/app/psagentai_agent.py
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
```
6. Enable and start each service:
```bash
sudo systemctl daemon-reload
sudo systemctl enable psagentai-user2
sudo systemctl start psagentai-user2
```
Recommended naming convention to avoid conflicts:
- Directories: `/opt/psagentai-user1/`, `/opt/psagentai-user2/`
- Services: `psagentai-user1.service`, `psagentai-user2.service`
--- ---
## 8) `.env` variables ## 8) Environment Variables Reference
### Telegram
| Variable | Required | Description | | Variable | Required | Description |
|---|---|---| |---|---|---|
| `AI_PROVIDER` | no | Preferred provider: `openrouter`, `stepfun`, `qwencloud` or `llamacpp` | | `TELEGRAM_BOT_TOKEN` | Yes | Telegram bot token from @BotFather |
| `TELEGRAM_BOT_TOKEN` | yes | Telegram bot token | | `TELEGRAM_CHAT_ID` | Yes | Target chat ID for proactive messages |
| `TELEGRAM_CHAT_ID` | yes | User chat ID |
| `DEFAULT_MODEL` | yes | Default AI model | ### AI Providers
| `OPENROUTER_API_KEY` | 1 of the keys | OpenRouter key |
| `STEPFUN_API_KEY` | 1 of the keys | StepFun key | | Variable | Required | Description |
| `QWENCLOUD_API_KEY` | 1 of the keys | QwenCloud key | |---|---|---|
| `MIN_INTERVAL_MINUTES` | no | Minimum interval for proactive messages | | `AI_PROVIDER` | Yes | Preferred provider: `openrouter`, `stepfun`, `qwencloud` or `llamacpp` |
| `MAX_INTERVAL_MINUTES` | no | Maximum interval for proactive messages | | `DEFAULT_MODEL` | Yes | Model identifier (provider-specific) |
| `MIN_MESSAGE_LINES` | no | Minimum lines per agent message | | `OPENROUTER_API_KEY` | Conditional | Required for OpenRouter |
| `AUTO_ENRICH_EVERY` | no | Enriches profile every N messages | | `OPENROUTER_API_URL` | No | OpenRouter API base URL |
| `AUTO_IMPROVE_EVERY` | no | Auto improvement every N messages | | `STEPFUN_API_KEY` | Conditional | Required for StepFun |
| `UPLOAD_CONTEXT_MAX_CHARS` | no | Character limit of upload sent to AI (`0` = no limit) | | `STEPFUN_API_URL` | No | StepFun API base URL |
| `VISION_MODEL` | no | AI model for image analysis | | `QWENCLOUD_API_KEY` | Conditional | Required for QwenCloud |
| `VISION_PROVIDER` | no | Vision model provider (`openrouter`, `stepfun`, `qwencloud`) | | `QWENCLOUD_API_URL` | No | QwenCloud API base URL |
| `LLAMA_CPP_API_URL` | No | llama.cpp server URL (default: `http://localhost:8080/v1`) |
| `FALLBACK_MODELS` | No | Comma-separated fallback models |
### Behavior 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 message |
| `MAX_HISTORY_LENGTH` | `50` | Max messages in conversation 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` | Maximum search results returned |
| `AUTO_ENRICH_EVERY` | `2` | Auto-enrich profiles every N messages (`0` = disabled) |
| `AUTO_IMPROVE_EVERY` | `20` | Auto-improve system every N messages (`0` = disabled) |
### Vision / Image Analysis
| Variable | Default | Description |
|---|---|---|
| `VISION_MODEL` | `meta-llama/llama-4-maverick-17b-128b-instruct` | Model for image analysis |
| `VISION_PROVIDER` | auto | Provider for vision model |
### Persistence
| Variable | Default | Description |
|---|---|---|
| `USER_PROFILE_FILE` | `user_profile.json` | User profile file path |
| `AGENT_PROFILE_FILE` | `agent_profile.json` | Agent profile file path |
| `CONTEXTS_DIR` | `contexts` | Conversation context directory |
--- ---
## Useful commands via Telegram ## 9) Backups
- `/viewai` — shows current AI provider and model Regularly back up the data files in the `app/` directory:
- `/configai` — interactively configures AI provider and model
- `/viewvision` — shows current vision provider and model
- `/configvision` — interactively configures vision model
- `/about` — displays system information, version, author and license
--- - `user_profile.json` — user profile data
- `agent_profile.json` — agent personality and traits
- `system_improvements.json` — auto-improvement history
- `uploads_metadata.json` — uploaded files index
- `config.json` — schedule configuration
- `contexts/` — conversation history by date
- `workspace/` — created and edited files
## 9) Important backups ### Daily backup example
Regularly backup the data files inside `/app`:
- `user_profile.json`
- `agent_profile.json`
- `system_improvements.json`
- `uploads_metadata.json`
- `contexts/` folder
- `workspace/` folder
Simple daily backup example:
```bash ```bash
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 contexts workspace # Create backups directory
sudo mkdir -p /root/backups
# Run daily backup
BACKUP_FILE="/root/backups/psagentai-$(date +%F).tar.gz"
tar czf "$BACKUP_FILE" -C /opt/psagentai/app \
user_profile.json \
agent_profile.json \
system_improvements.json \
uploads_metadata.json \
config.json \
contexts \
workspace
echo "Backup created: $BACKUP_FILE"
``` ```
### Automated backup with cron
```bash
sudo crontab -e
```
Add:
```cron
0 2 * * * /usr/bin/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
```
This creates a backup every day at 2:00 AM.
--- ---
## 10) Security ## 10) Security
- Never commit `.env` to the repository. - **Never commit `.env`** to version control. Add it to `.gitignore`.
- Restrict permissions: `chmod 600 .env`. - **Restrict permissions**: `chmod 600 .env` to prevent other users from reading secrets.
- Use an exclusive user for each service instance. - **Use dedicated users**: Run each instance under its own system user for isolation.
- For greater isolation, run each instance in a separate Docker container or on distinct VMs. - **Firewall**: Only expose necessary ports (typically only outbound HTTPS is needed).
- **API keys**: Rotate keys periodically and monitor usage for anomalies.
- **Path validation**: The agent validates file paths to prevent directory traversal attacks.
- **Sensitive data**: Emails and phone numbers in profiles are preserved but not exposed in logs.
---
## Useful Telegram Commands for Administration
- `/viewai` — Check current AI provider and model
- `/configai` — Change AI provider/model on the fly
- `/viewvision` — Check vision configuration
- `/configvision` — Change vision model on the fly
- `/debug` — View system debug information
- `/reload` — Reload .env without restarting the service
- `/timezone` — Check server timezone
---
## Support
- System developed by: [Syspanel.com.br](https://syspanel.com.br)
- Author: Marco A. S. Costa
- Email: contato@syspanel.com.br
- License: Proprietary for syspanel.com.br
README.md
+222 -65
View File
@@ -1,43 +1,86 @@
# PsAgentAI - Personal Conversational AI Agent # PsAgentAI - Personal Conversational AI Agent
Personal Conversational AI Agent system via Telegram that behaves as a personal companion, chatting, cooperating and maintaining continuous context with the user. 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.
## Structure ## 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
- **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/ app/
├── psagentai_agent.py # Main agent code ├── psagentai_agent.py # Main agent code (~5000 lines)
├── iniciar.sh # Installation and execution script ├── iniciar.sh # Setup and run script
├── requirements.txt # Python dependencies ├── requirements.txt # Python dependencies
├── .env # Local settings (do not commit) ├── .env # Local settings (do not commit)
├── .env.example # Configuration example ├── user_profile.json # User profile (auto-created)
├── user_profile.json # User profile ├── agent_profile.json # Agent profile (auto-created)
├── agent_profile.json # Agent profile (personality, traits, notes) ├── uploads_metadata.json # Uploaded files metadata (auto-created)
├── contexts/ # Conversation history by date ├── config.json # Schedule configuration (auto-created)
├── system_improvements.json # Auto-improvement history (auto-created)
├── contexts/ # Conversation history by date
│ └── YYYY-MM-DD.json │ └── YYYY-MM-DD.json
├── workspace/ # Created and edited files
│ └── projects/
├── README.md ├── README.md
├── DEPLOY.md
├── RULES.md
└── LICENSE └── LICENSE
``` ```
## Prerequisites ## Prerequisites
- Python 3.9+ - Python 3.9+
- Telegram account with bot created via @BotFather - Telegram account with a bot created via [@BotFather](https://t.me/BotFather)
- At least one supported AI API key - At least one supported AI API key (OpenRouter, StepFun, or QwenCloud)
## Configuration ## Configuration
1. Copy `.env.example` to `.env` and fill in: 1. Copy `.env` from the example or create it manually:
- `TELEGRAM_BOT_TOKEN` — Telegram bot token
- `TELEGRAM_CHAT_ID` — your Telegram chat ID
- `OPENROUTER_API_KEY` or other compatible API key
2. Adjust intervals if desired: ```bash
- `MIN_INTERVAL_MINUTES` cp .env.example .env # if .env.example exists
- `MAX_INTERVAL_MINUTES` nano .env
- `MIN_MESSAGE_LINES` — defines the minimum number of lines per agent message (default: `15`) ```
## Installation and execution 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
```bash ```bash
cd app cd app
@@ -45,71 +88,185 @@ chmod +x iniciar.sh
./iniciar.sh ./iniciar.sh
``` ```
The script creates the virtual environment, installs dependencies and starts the agent. 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
## Features ## Running
- Initial onboarding with questions to build the profile ```bash
- Conversation history by day in `contexts/` # From the app directory:
- User profile persisted in `user_profile.json` python3 psagentai_agent.py
- Agent profile persisted in `agent_profile.json` (name, personality, traits and notes)
- Proactive messages at configurable random intervals
- Minimum lines per agent message configurable via `.env`
- Support for multiple AI providers:
- OpenRouter
- StepFun
- QwenCloud
- llama.cpp (local)
- Dynamic profile update via natural commands in chat
## Available commands # Or use the setup script:
./iniciar.sh
```
- `/start` — starts or restarts the conversation ## Available Commands
- `/help` — displays help
- `/profile` — shows user and agent profile summary
- `/agentprofile` — shows only the agent profile
- `/reset` — resets user and agent profiles
- `/clear` — deletes all data (profiles, contexts, chat_id)
- `/onboarding` — restarts onboarding
- `/newconfig` — reconfigures everything from scratch
- `/cancel` — cancels ongoing operation
- `/viewai` — shows current AI provider and model
- `/configai` — interactively configures AI provider and model with button selection
- `/about` — displays system information, version, author and license
- `/viewvision` — shows current vision provider and model
- `/configvision` — interactively configures vision model with button selection
- `/download <name>` — downloads a workspace file by name
## Editing workspace files ### 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
You can ask to edit existing files in `workspace/` using commands like: ### 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` - `edit the file test.txt and add line 4`
- `modify the file hello.py to print hello world` - `modify the file hello.py to print hello world`
- `in the file test.txt replace Line 2 with Line 2 edited` - `in the file test.txt replace Line 2 with Line 2 edited`
The Agent will locate the file, apply the requested change and save the result. ### Daily Routine and Schedule
- `/addtouserprofile <text>` — updates information in your profile - `/schedule` — Set days and times for automatic messages
- `/addtoagentprofile <text>` — adds characteristics to the agent profile - `/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
## Updating profile during conversation ### 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
### User profile ### Utilities
- `/debug` — Shows system debug information
- `/reload` — Reload .env settings without restarting
- `/timezone` — Shows the server timezone (read-only)
You can update your profile at any time using phrases like: ### Natural Language Profile Updates
During conversation, you can update profiles using phrases:
**User profile:**
- `Include this in my profile: ...` - `Include this in my profile: ...`
- `Note in my profile: ...` - `Note in my profile: ...`
- `Add to my profile: ...` - `Add to my profile: ...`
- `Save in my profile: ...` - `Save in my profile: ...`
### Agent profile **Agent profile:**
Use `/addtoagentprofile <text>` to add characteristics to the agent profile.
Or use phrases like:
- `Include this in the agent profile: ...` - `Include this in the agent profile: ...`
- `Note 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:
```bash
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 ## License
Proprietary use. See the `LICENSE` file. Proprietary for Syspanel.com.br. See `LICENSE` file.
RULES.md
+5 -4
View File
@@ -11,6 +11,7 @@ Official rules for AIs and developers to code the PsAgentAI system correctly, st
- **Language:** Python 3.9+ - **Language:** Python 3.9+
- **Framework:** python-telegram-bot (v20+) - **Framework:** python-telegram-bot (v20+)
- **Main file:** `psagentai_agent.py` - **Main file:** `psagentai_agent.py`
- **Entry script:** `iniciar.sh`
- **Purpose:** Personal conversational companion with memory, profiles, file workspace, image analysis, web search and automations. - **Purpose:** Personal conversational companion with memory, profiles, file workspace, image analysis, web search and automations.
### Basic rule ### Basic rule
@@ -236,10 +237,10 @@ Always use the existing helper functions:
## 15. Language and Communication ## 15. Language and Communication
- Bot interface: Brazilian Portuguese. - Bot interface: English.
- Agent replies: Brazilian Portuguese. - Agent replies: English.
- Logs and code: technical English for variable/function names; Portuguese for user-facing messages. - Logs and code: technical English for variable/function names; English for user-facing messages.
- Documentation: Brazilian Portuguese. - Documentation: English.
--- ---
__pycache__/psagentai_agent.cpython-311.pyc
BIN
View File
Binary file not shown.
psagentai_agent.py
+1997 -23
View File
File diff suppressed because it is too large Load Diff