Expert knowledge for working with BerinIA, an autonomous AI agent ecosystem for commercial prospection automation. Comprehensive rules for backend development, database interaction, testing, and multi-service management.
Expert guidance for developing and maintaining BerinIA, an autonomous AI agent ecosystem designed for commercial prospection automation. This skill provides comprehensive rules and workflows for backend development, database operations, multi-service management, and system integration.
BerinIA is a complex multi-service system consisting of:
**ABSOLUTE REQUIREMENTS:**
1. **Never call `fs.readFileSync()` or equivalent without verifying the path is a file**
- ALWAYS use `fs.statSync(path).isFile()` before reading
2. **Never pass a directory as argument to read operations**
- Validate paths using `fs.existsSync()` and `fs.lstatSync()`
3. **Log debug information for dynamic/unknown paths before accessing**
4. **Wrap all file operations in try/catch blocks**
- Never allow process crashes from file errors
5. **EISDIR errors are FORBIDDEN**
- Their occurrence indicates failed validation checks
```python
import os
from pathlib import Path
def safe_read_file(file_path: str) -> str:
path = Path(file_path)
# Validation checks
if not path.exists():
raise FileNotFoundError(f"Path does not exist: {file_path}")
if path.is_dir():
raise IsADirectoryError(f"Path is a directory, not a file: {file_path}")
if not path.is_file():
raise ValueError(f"Path is not a regular file: {file_path}")
# Safe to read
try:
return path.read_text()
except Exception as e:
raise RuntimeError(f"Failed to read {file_path}: {e}")
```
**ZERO TOLERANCE RULE:**
❌ **ABSOLUTELY FORBIDDEN:**
✅ **REQUIRED:**
**Objective:** Never create the illusion that something works. Simulated or fake behavior is considered a critical failure.
**Before ANY modification:**
1. Activate Python virtual environment:
```bash
source /root/berinia/.venv/bin/activate
```
2. Database location: `/root/berinia/backend`
**Workflow:**
1. **Always check if file exists before creating**
```python
from pathlib import Path
file_path = Path("new_file.py")
if file_path.exists():
print(f"File already exists: {file_path}")
# Decide: modify, skip, or ask user
```
2. **Never overwrite stable files without justification**
3. **All tests go in:** `/root/berinia/infra-ia/tests`
**Non-negotiable:**
**Every functional change requires documentation:**
1. **If topic exists:** Update existing file
2. **If topic is new:** Create new file in `infra-ia/documentation`
3. **If related file exists:** Extend existing documentation (avoid duplication)
**Before writing:**
**Documentation structure:**
```
infra-ia/documentation/
├── résumé/
│ └── synthèse_système_BerinIA.md # Complete system summary
├── architecture/
│ ├── ARCHITECTURE.md # Detailed architecture
│ ├── overview.md # Simplified view
│ ├── agents-system.md # Agent system details
│ └── communication.md # Component communication
├── integrations/
│ ├── database.md # Database integration
│ ├── sms-twilio.md # Twilio SMS
│ └── instantly.md # Instantly.ai
├── services/
│ ├── systemd_services.md # Systemd services
│ └── env_variables_api.md # Environment variables
├── api.md # API documentation
└── api_usage_guide_for_ai.md # AI API usage guide
```
**Strict requirement:**
```bash
pnpm install
pnpm add <package>
pnpm run dev
npm install # Never do this
npm i <package> # Never do this
```
| Service | Description | Dependencies | Port |
|---------|-------------|--------------|------|
| berinia-api.service | Main backend API | PostgreSQL | 8000 |
| berinia-next.service | Next.js frontend | berinia-api | 3000 |
| berinia-webhook.service | External event webhooks | berinia-api | 8001 |
| berinia-qdrant.service | Vector database | Docker | 6333 |
| berinia-agents.service | AI agent runtime | PostgreSQL, Qdrant | - |
| berinia-scheduler.service | Task scheduler | PostgreSQL | - |
| berinia-telegram-bot.service | Telegram bot (v1 only) | berinia-api | - |
1. **Database services:**
- PostgreSQL (system service)
- `berinia-qdrant.service`
2. **API services:**
- `berinia-api.service`
- `berinia-webhook.service`
3. **Agent services:**
- `berinia-agents.service`
- `berinia-scheduler.service`
4. **Frontend & integrations:**
- `berinia-next.service`
- `berinia-telegram-bot.service`
```bash
sudo systemctl start berinia-api.service
sudo systemctl stop berinia-api.service
sudo systemctl restart berinia-api.service
sudo systemctl status berinia-api.service
sudo journalctl -u berinia-api.service -f
sudo systemctl enable berinia-api.service
```
**Reference:** `./architecture/overview.md` and `./services/systemd_services.md`
```bash
source /root/berinia/.venv/bin/activate
pnpm install
sudo systemctl start berinia-qdrant.service
sudo systemctl start berinia-api.service
```
**Natural language interface:**
```bash
python interact.py
```
**API access:**
```bash
curl http://localhost:8000/api/services/
```
**Log monitoring:**
```bash
sudo journalctl -f
sudo journalctl -u berinia-agents.service -f
curl http://localhost:8000/api/logs/
```
**Location:** `/root/berinia/infra-ia/tests`
**Example test structure:**
```python
import pytest
from pathlib import Path
import sys
sys.path.insert(0, str(Path(__file__).parent.parent / "backend"))
from database import get_db_connection
def test_real_database_query():
"""Test with REAL database - no mocks allowed"""
conn = get_db_connection()
cursor = conn.cursor()
# Real query
cursor.execute("SELECT COUNT(*) FROM agents")
result = cursor.fetchone()
assert result is not None
assert result[0] >= 0 # Real count from database
conn.close()
def test_api_endpoint():
"""Test with REAL API - no simulation"""
import requests
response = requests.get("http://localhost:8000/api/agents/")
assert response.status_code == 200
data = response.json()
# Verify real data structure
assert isinstance(data, list)
# Further assertions based on actual data...
```
**When to document:**
**How to document:**
```bash
cd /root/berinia/infra-ia/documentation
ls -la architecture/
ls -la integrations/
ls -la services/
nano architecture/new-feature.md
```
**Template for new documentation:**
```markdown
Brief overview of what this feature does.
How it fits into the system.
Required environment variables, settings.
Examples and API endpoints.
Related services and components.
How to test this feature (with real data).
Common issues and solutions.
```
**Location:** `/root/berinia/backend`
**Reference:** `./integrations/database.md`
**Connection example:**
```python
import psycopg2
from psycopg2.extras import RealDictCursor
def get_db_connection():
return psycopg2.connect(
dbname="berinia",
user="berinia_user",
password=os.getenv("DB_PASSWORD"),
host="localhost",
cursor_factory=RealDictCursor
)
```
**Port:** 6333
**Reference:** `./architecture/agents-system.md`
```python
from qdrant_client import QdrantClient
client = QdrantClient(host="localhost", port=6333)
```
**Reference:** `./integrations/sms-twilio.md`
**Reference:** `./integrations/instantly.md`
**Reference:** `./services/env_variables_api.md`
**Key variables:**
```bash
systemctl list-units "berinia-*" --all
curl http://localhost:8000/health
curl http://localhost:6333/health
```
**Database backup:**
```bash
pg_dump berinia > backup_$(date +%Y%m%d_%H%M%S).sql
```
**Service logs:**
```bash
sudo journalctl -u berinia-agents.service --since today > agents.log
```
**File access errors (EISDIR):**
**Service won't start:**
```bash
systemctl status postgresql.service
systemctl status berinia-qdrant.service
sudo journalctl -u berinia-api.service -n 50
source /root/berinia/.venv/bin/activate
python -c "import sys; print(sys.prefix)"
```
**Database connection failures:**
```bash
psql -U berinia_user -d berinia
```
**Agent execution errors:**
1. **Type hints everywhere:**
```python
def process_agent_result(agent_id: int, result: dict) -> bool:
pass
```
2. **Error handling:**
```python
try:
result = risky_operation()
except SpecificError as e:
logger.error(f"Operation failed: {e}")
raise
finally:
cleanup()
```
3. **Logging:**
```python
import logging
logger = logging.getLogger(__name__)
logger.info("Processing started")
logger.error("Error details", exc_info=True)
```
1. **Real data only** (no mocks)
2. **Integration tests** over unit tests
3. **End-to-end workflows** validated
4. **Database state verified** before and after
5. **API responses checked** for correctness
1. **Keep it current** - update with every change
2. **Be specific** - include examples and commands
3. **Link related docs** - create a web of knowledge
4. **Use consistent structure** - follow existing templates
```
/root/berinia/
├── backend/ # Database & API
├── infra-ia/
│ ├── documentation/ # All documentation
│ └── tests/ # Test files
├── .venv/ # Python environment
└── frontend/ # Next.js app
```
```bash
source /root/berinia/.venv/bin/activate
python interact.py
systemctl list-units "berinia-*"
sudo systemctl restart berinia-api.service
sudo journalctl -u berinia-agents.service -f
pnpm add <package>
pip install <package>
```
This skill encapsulates complex multi-service system knowledge. When working with BerinIA:
1. **Start with documentation** - review relevant files before changes
2. **Validate thoroughly** - file operations, service dependencies, data sources
3. **Test with real data** - no shortcuts or simulations
4. **Document immediately** - keep knowledge current
5. **Follow service order** - respect dependencies on startup/shutdown
6. **Monitor logs actively** - catch issues early
The system's reliability depends on strict adherence to these practices, particularly around file validation, real data usage, and comprehensive testing.
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/berinia-system-development-and-operations/raw