marcocosta10000
9eed02645b
Adds a post-generation validation step that checks whether a search-grounded reply is actually supported by the retrieved results: it extracts cited URLs from the response and flags replies that claim to have searched without citing any of the provided sources, as well as replies containing specific numbers or dates absent from the results. Also switches the default model to xiaomi/mimo-v2.6-flash and documents the anti-hallucination behavior in the README.
274 lines
10 KiB
Markdown
Executable File
274 lines
10 KiB
Markdown
Executable File
# 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](https://t.me/BotFather)
|
|
- At least one supported AI API key (OpenRouter, StepFun, or QwenCloud)
|
|
|
|
## Configuration
|
|
|
|
1. Copy `.env` from the example or create it manually:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```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
|
|
|
|
Proprietary for Syspanel.com.br. See `LICENSE` file.
|