TROUBLESHOOTING

PATAS Troubleshooting

Troubleshooting

---

API Issues

Problem: API not responding

Symptoms:

• curl http://localhost:8000/api/v1/health not working
• Connection refused

Solution:

1. Check if the server is running:

   ps aux | grep uvicorn

2. Check the port:

   lsof -i :8000

3. Restart the server:

   poetry run uvicorn app.api.main:app --host 0.0.0.0 --port 8000

---

Problem: 400 Bad Request

Symptoms:

• {"detail": "Empty messages list"}
• {"detail": "Invalid data"}

Solution:

1. Check request format:

   # Correct
   {
     "messages": [
       {"id": "1", "text": "message", "is_spam": True}
     ]
   }
   
   # Incorrect
   {
     "message": {...}  # Should be "messages" (plural)
   }

2. Проверьте обязательные поля: text required
3. Проверьте типы данных: is_spam must be boolean

---

Problem: 500 Internal Server Error

Symptoms:

• {"detail": "Pattern mining failed: ..."}

Solution:

1. Check server logs
2. Check database connection:

   # Check DATABASE_URL in .env
   echo $DATABASE_URL

3. Check database availability:

   sqlite3 data/spamapi.db "SELECT COUNT(*) FROM messages;"

---

Pattern Mining Issues

Problem: patterns not being created

Symptoms:

• patterns_created: 0 after mining
• no patterns in response

Solution:

1. Check if there are spam messages:

   # Check via API
   response = requests.get("http://localhost:8000/api/v1/patterns")

2. Decrease min_spam_count:

   requests.post(
       "http://localhost:8000/api/v1/patterns/mine",
       json={"min_spam_count": 3}  # Instead of 10
   )

3. Check if messages are marked as spam:

   # Ensure is_spam=True in messages

---

Problem: Pattern mining slow

Symptoms:

• Mining takes a long time
• Timeout errors

Solution:

1. Decrease days:

   requests.post(
       "http://localhost:8000/api/v1/patterns/mine",
       json={"days": 1}  # Instead of 7
   )

2. Disable LLM:

   json={"use_llm": False}

3. Decrease PATTERN_MINING_CHUNK_SIZE в .env

---

Rule Issues

Problem: Rules not being promoted

Symptoms:

• promoted_count: 0 after promote
• Rules remain in shadow status

Solution:

1. Check rule metrics:

   response = requests.get(
       "http://localhost:8000/api/v1/rules",
       params={"status": "shadow", "include_evaluation": True}
   )
   rules = response.json()
   
   for rule in rules:
       eval_data = rule.get("evaluation")
       if eval_data:
           print(f"Rule {rule['id']}: precision={eval_data.get('precision')}")

2. Check AGGRESSIVENESS_PROFILE:

   # Conservative requires precision >= 0.95
   # if precision < 0.95, rules are not promoted

3. Ensure rules were evaluated:

   requests.post("http://localhost:8000/api/v1/rules/eval-shadow")

---

Problem: Rules have low precision

Symptoms:

• precision: 0.50 or lower
• Many ham hits

Solution:

1. Check rule SQL expression:

   response = requests.get("http://localhost:8000/api/v1/rules")
   for rule in response.json():
       print(f"Rule {rule['id']}: {rule['sql_expression']}")

2. Use LLM validation:

   # Enable LLM validation during mining
   requests.post(
       "http://localhost:8000/api/v1/patterns/mine",
       json={"use_llm": True, "enable_llm_validation": True}
   )

3. Используйте conservative profile for stricter rules

---

LLM Issues

Problem: LLM not working

Symptoms:

• use_llm: true but LLM is not used
• Errors during LLM calls

Solution:

1. Check API key:

   echo $OPENAI_API_KEY
   # or
   echo $PATAS_OPENAI_API_KEY

2. Проверьте LLM_PROVIDER:

   # Should be "openai", not "none"
   grep LLM_PROVIDER .env

3. Check network access:

   curl https://api.openai.com/v1/models \
     -H "Authorization: Bearer $OPENAI_API_KEY"

---

Problem: LLM slow

Symptoms:

• LLM calls take a long time
• Timeout errors

Solution:

1. Use a faster model:

   LLM_MODEL=gpt-4o-mini  # Instead of gpt-4

2. Decrease количество примеров for LLM
3. Use semantic mining instead of LLM for some patterns

---

Database Issues

Problem: Database connection error

Symptoms:

• sqlalchemy.exc.OperationalError
• Database locked

Solution:

1. Проверьте DATABASE_URL:

   echo $DATABASE_URL

2. Check database access permissions:

   ls -la data/spamapi.db

3. for SQLite, ensure no other processes are using the database

---

Problem: Database migration issues

Symptoms:

• Tables not created
• Schema errors

Solution:

1. Initialize database:

   from app.database import init_db
   import asyncio
   asyncio.run(init_db())

2. or via CLI:

   poetry run python -c "from app.database import init_db; import asyncio; asyncio.run(init_db())"

---

Configuration Issues

Problem: Settings not being applied

Symptoms:

• Changes in .env not working
• Old values are being used

Solution:

1. Restart server after changing .env
2. Check if .env is loaded:

   from app.config import settings
   print(settings.aggressiveness_profile)

3. Ensure .env is in the correct directory

---

Performance Issues

Problem: Slow Processing

Symptoms:

• Requests take a long time
• High latency

Solution:

1. Use batch endpoints for large datasets
2. Decrease PATTERN_MINING_CHUNK_SIZE
3. Disable LLM if not нужен
4. Use async for multiple requests
5. Check database performance

---

Getting Help

if Problem not resolved:

1. Check logs:

   tail -f logs/app.log

2. Check health endpoint:

   curl http://localhost:8000/api/v1/health

3. Create an issue с:

   • Problem description
   • Logs
   • Configuration (without secrets)
   • Steps to reproduce

---

Additional Resources

• API Reference — API documentation
• Configuration Guide — settings
• Integration Guide — Integration