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 with headless browser fallback, analyzes images, visits websites directly, 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 with headless browser fallback for JS-rendered e-commerce sites
- **Direct website access**: Visit and analyze any website by name — the agent can enter sites and extract their content
- **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/
│   └── web_cache/              # Cached webpage content (auto-created)
├── 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 |
| `WEB_SEARCH_SCRAPE_ENABLED` | `true` | Fetch page content for search results (uses headless browser fallback) |
| `WEB_SEARCH_SCRAPE_CACHE_TTL` | `3600` | Cache TTL for scraped pages in seconds |
| `WEB_SEARCH_SCRAPE_MAX_CHARS` | `15000` | Max characters per scraped page |
| `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. If HTTP scraping fails (JS-rendered sites), it falls back to a headless Chromium browser via Playwright.
7. **Direct Website Access**: You can ask the agent to visit any website by name or URL. It fetches the page content using a headless browser (or HTTP scrape for static sites) and extracts the readable text.
8. **Vision**: Images are analyzed using the configured vision model
9. **Auto-improvement**: The system periodically analyzes conversations and suggests improvements

## Web Search & Website Access

### How Web Search Works

When you ask a question that requires current information, the agent:
1. Runs a DuckDuckGo search to find relevant results
2. Fetches page content from each result using HTTP scraping + BeautifulSoup
3. For JS-rendered sites (e-commerce, SPAs), automatically falls back to a headless Chromium browser via Playwright
4. Extracts readable text, strips scripts/styles, and passes it to the AI for grounded responses
5. Validates the response against source data to prevent hallucination

The system caches scraped pages for 1 hour (configurable via `WEB_SEARCH_SCRAPE_CACHE_TTL`).

### Direct Website Visit

You can ask the agent to enter or analyze any website:

- `Entre no site syspanel.com.br e me diga do que se trata`
- `Analisa https://www.google.com para mim`
- `Visite este site e verifique os preços`

The agent detects URLs + action keywords (entra, acesse, analise, visite, pesquise, etc.) and automatically scrapes the page. It uses:
1. Headless Chromium (Playwright) — best for JS-rendered/spa sites like KaBuM, MercadoLivre, Buscape
2. HTTP scraping (BeautifulSoup) — fallback for static sites
3. Cache — previously fetched pages are reused from `workspace/web_cache/`

**Supported websites**: Most informational sites, blogs, news portals, e-commerce product listing pages. Sites with heavy bot protection (Cloudflare CAPTCHA) may not work.

### Example Use Cases

- **Price comparison**: `Encontre os SSD de 120GB mais baratos e me informe detalhes e link de compra` → agent searches and fetches real prices from KaBuM/Zoom/Buscape
- **Website analysis**: `Entre no site syspanel.com.br e me diga do que se trata` → agent visits and summarizes the site
- **Current events**: `Pesquisa na internet as notícias sobre tecnologia` → agent searches and reads article content

## 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`
- **Web search results empty**: Check that web scraping works — e-commerce sites (KaBuM, MercadoLivre) require Playwright + Chromium. Reinstall with `./iniciar.sh`. Sites with CAPTCHA protection may fail regardless.
- **Website visit fails**: Some sites block headless browsers or show CAPTCHA. Try simpler informational sites first. The agent shows `[URL_VISIT] failed to fetch url=...` in console output if fetching fails.

## Dependencies

### Python packages

All listed in `requirements.txt`:
- `python-telegram-bot` — Telegram bot framework
- `requests` + `beautifulsoup4` + `lxml` — HTTP scraping for static pages
- `playwright` — Headless Chromium for JS-rendered/spa sites (e-commerce, dynamic content)
- `openai` — OpenAI-compatible AI API client
- `PyMuPDF`, `python-docx`, `Pillow`, `SpeechRecognition`, `pydub` — File processing

### System packages

- `ffmpeg` — Voice message processing
- `chromium-browser` — Installed automatically by Playwright (`playwright install chromium`)

Run `./iniciar.sh` to set up all dependencies including browser installation.

## Development

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

## License

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