# 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.

## Structure

```
app/
├── psagentai_agent.py          # Main agent code
├── iniciar.sh               # Installation and execution script
├── requirements.txt         # Python dependencies
├── .env                     # Local settings (do not commit)
├── .env.example             # Configuration example
├── user_profile.json        # User profile
├── agent_profile.json       # Agent profile (personality, traits, notes)
├── contexts/                # Conversation history by date
│   └── YYYY-MM-DD.json
├── README.md
└── LICENSE
```

## Prerequisites

- Python 3.9+
- Telegram account with bot created via @BotFather
- At least one supported AI API key

## Configuration

1. Copy `.env.example` to `.env` and fill in:
   - `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:
   - `MIN_INTERVAL_MINUTES`
   - `MAX_INTERVAL_MINUTES`
   - `MIN_MESSAGE_LINES` — defines the minimum number of lines per agent message (default: `15`)

## Installation and execution

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

The script creates the virtual environment, installs dependencies and starts the agent.

## Features

- Initial onboarding with questions to build the profile
- Conversation history by day in `contexts/`
- User profile persisted in `user_profile.json`
- 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

- `/start` — starts or restarts the conversation
- `/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

You can ask to edit existing files in `workspace/` using commands like:
- `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`

The Agent will locate the file, apply the requested change and save the result.
- `/addtouserprofile <text>` — updates information in your profile
- `/addtoagentprofile <text>` — adds characteristics to the agent profile

## Updating profile during conversation

### User profile

You can update your profile at any time using phrases like:

- `Include this in my profile: ...`
- `Note in my profile: ...`
- `Add to my profile: ...`
- `Save in my profile: ...`

### Agent profile

Use `/addtoagentprofile <text>` to add characteristics to the agent profile.
Or use phrases like:

- `Include this in the agent profile: ...`
- `Note in the agent profile: ...`

## License

Proprietary use. See the `LICENSE` file.