Development guidelines for BerinIA, an autonomous AI agent ecosystem for commercial prospection automation. Ensures proper file handling, testing, documentation, and real data validation.
Expert skill for developing and maintaining BerinIA, an AI agent ecosystem for autonomous commercial prospection automation.
BerinIA is a complex multi-service architecture consisting of:
**CRITICAL: Never perform file operations on directories**
Before any file read operation:
```python
import os
from pathlib import Path
def safe_read_file(path):
if not os.path.exists(path):
raise FileNotFoundError(f"Path does not exist: {path}")
if not os.path.isfile(path):
raise IsADirectoryError(f"Path is a directory, not a file: {path}")
# Now safe to read
with open(path, 'r') as f:
return f.read()
```
**Enforcement rules:**
**Always activate Python virtual environment before any operation:**
```bash
source /root/berinia/.venv/bin/activate
```
**Database location:** `/root/berinia/backend`
**All functionality must use REAL DATA ONLY**
**ABSOLUTE PROHIBITION:**
**Required approach:**
**Testing workflow:**
1. Test immediately after any modification
2. Never mark task complete while errors exist
3. Validate against production-like conditions
4. Use real database queries for statistics/displays
**Documentation is mandatory for all changes**
**Before creating documentation:**
1. Check if topic already exists in `infra-ia/documentation`
2. If exists: **update existing file**
3. If related file exists: **extend it** (avoid duplication)
4. If truly new: **create new file** in proper section
**Documentation structure:**
```
infra-ia/documentation/
├── résumé/
│ └── synthèse_système_BerinIA.md
├── architecture/
│ ├── ARCHITECTURE.md
│ ├── overview.md
│ ├── agents-system.md
│ └── communication.md
├── integrations/
│ ├── database.md
│ ├── sms-twilio.md
│ └── instantly.md
├── services/
│ ├── systemd_services.md
│ └── env_variables_api.md
└── guides/
└── api_usage_guide_for_ai.md
```
**Documentation principles:**
**Strict requirement: Use `pnpm` exclusively**
Before creating any file:
1. Check if file already exists
2. Never overwrite stable files without justification
3. Verify location is appropriate for file type
4. Test files go to `/root/berinia/infra-ia/tests`
| Service | Port | Dependencies | Purpose |
|---------|------|--------------|---------|
| berinia-api.service | 8000 | PostgreSQL | Main backend API |
| berinia-next.service | 3000 | berinia-api | Next.js frontend |
| berinia-webhook.service | 8001 | berinia-api | External event receiver |
| berinia-qdrant.service | 6333 | Docker | Vector database |
| berinia-agents.service | - | PostgreSQL, qdrant | AI agent runtime |
| berinia-scheduler.service | - | PostgreSQL | Task scheduler |
| berinia-telegram-bot.service | - | berinia-api | Telegram integration (v1 only) |
**Service startup order:**
1. Database services (PostgreSQL, qdrant)
2. API services (berinia-api, webhook)
3. Agent services (agents, scheduler)
4. Frontend/integrations (next, telegram)
```bash
systemctl status berinia-api
systemctl status berinia-agents
sudo systemctl start berinia-api
sudo systemctl start berinia-agents
journalctl -u berinia-api -f
```
```bash
cd /root/berinia
source .venv/bin/activate
python interact.py
```
All errors must be:
1. Caught with try/catch blocks
2. Logged appropriately
3. Never crash the process
4. Provide actionable error messages
**Example:**
```python
try:
# Validate path
if not os.path.isfile(filepath):
logger.error(f"Expected file but got directory: {filepath}")
raise IsADirectoryError(filepath)
# Perform operation
with open(filepath, 'r') as f:
data = f.read()
except IsADirectoryError as e:
logger.error(f"Directory error: {e}")
return {"error": "Invalid file path"}
except Exception as e:
logger.error(f"Unexpected error: {e}")
return {"error": "Operation failed"}
```
**Critical principles:**
**Validation checklist:**
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/berinia-multi-agent-system-development/raw