FAQ tecnica
Arquitectura y rendimiento
¿Por que LangGraph para el agente ReAct?
LangGraph permite definir el ciclo razonamiento→accion→observacion como un grafo de estados, lo que facilita el control de flujo, el manejo de errores en mid-flight y la extension del agente con nuevos nodos.
¿Cuanto tarda una investigacion completa?
Con qwen3:14b y conexion a internet decente:
- Query unica (1 IOC, ~6 herramientas): 30-90 segundos
- Investigacion completa con pivot (1 IOC + 2-3 relacionados): 2-5 minutos
- Batch de 10 IOCs: 5-15 minutos (con delay de 2s entre cada uno)
¿Por que SQLite y no PostgreSQL?
Diseño deliberado: SQLite no requiere servidor, funciona en cualquier entorno, es suficiente para el volumen tipico de investigaciones OSINT, y los datos quedan en un fichero facil de hacer backup o migrar.
¿Cuantas investigaciones puede manejar SQLite?
En las pruebas, SQLite con WAL mode maneja sin problemas hasta decenas de miles de evidencias y millones de chunks. Para uso individual o de equipo pequeno, nunca sera el cuello de botella.
¿Como funciona el auto-pivot?
Cuando una herramienta devuelve un resultado que contiene IOCs relacionados (por ejemplo, VirusTotal devuelve dominios asociados a una IP), pivot_investigate los extrae. El agente evalua si alguno de esos IOCs es suficientemente interesante para investigar y, si lo es, lo añade a la cola. El parametro MAX_PIVOTS limita la profundidad para evitar explosion combinatoria.
¿ChromaDB puede hacer busqueda cross-investigation?
Si. La funcion cross_search en src/vector/store.py permite buscar sobre multiples colecciones de investigacion simultaneamente.
¿El modelo de embeddings soporta espanol?
Si. paraphrase-multilingual-MiniLM-L12-v2 es multilingue con soporte nativo para espanol, ingles, frances, aleman y otros 50 idiomas. Las busquedas semanticas funcionan igual de bien con texto en espanol.
Seguridad y privacidad
¿Las queries a VirusTotal son publicas?
En el free tier, VirusTotal puede usar tus queries para mejorar sus modelos. Revisa sus terminos de servicio. En tiers de pago hay opciones de privacidad. Para IOCs muy sensibles, usa Ollama + herramientas gratuitas.
¿Puedo ejecutar el MCP Server sin autenticacion en red publica?
No recomendado. El MCP Server en modo HTTP no incluye autenticacion por defecto. Si necesitas exponerlo, ponlo detras de un proxy con autenticacion (nginx + basic auth, o un VPN).
¿Los API keys estan seguros en .env?
El fichero .env esta en .gitignore. Si usas Claude Code u otros agentes, verifica que no los indexen. Para produccion, usa variables de entorno del sistema o un gestor de secretos (HashiCorp Vault, AWS Secrets Manager, etc.).
Desarrollo y extension
¿Como añado una nueva herramienta OSINT?
- Crea
src/tools/mi_herramienta.pycon una funcion async decorada con@cached - Registrala en
src/agent/__init__.py - Añade el endpoint en
src/mcp_server/server.py - Escribe tests en
tests/tools/test_mi_herramienta.pyusandorespx.mock - Documenta la key en
.env.example
Ver Desarrollo → Contribuir para el tutorial completo.
¿Puedo usar un modelo LLM distinto de los soportados?
Con el adapter de LangChain puedes usar cualquier modelo compatible. Edita src/agent/__init__.py y cambia el inicializador del LLM. El requisito es que el modelo soporte function/tool calling.
¿Los tests necesitan API keys reales?
No. Todos los tests de herramientas usan respx.mock para simular las respuestas HTTP. Puedes ejecutar toda la suite de tests sin ninguna API key configurada.
¿Como contribuir una traduccion de la documentacion web?
La documentacion web (este sitio) esta en osint-ai-one-web. Puedes traducir cualquier pagina creando el fichero equivalente en src/content/docs/<idioma>/.
Modelos y LLM
¿Por que Qwen3 y no LLaMA?
Qwen3 tiene excelente soporte de tool calling en Ollama y soporte multilingue nativo. LLaMA 3 tambien funciona, pero el tool calling es menos fiable en las versiones de Ollama actuales para ese modelo.
¿Puedo usar modelos cuantizados?
Si. Ollama soporta modelos cuantizados (Q4, Q8). Los modelos Qwen3 estan disponibles en varias cuantizaciones. La cuantizacion Q4 reduce el uso de RAM a la mitad con una perdida de calidad pequena.
¿El agente puede usar herramientas en paralelo?
El agente ReAct es secuencial por diseño (razona sobre cada resultado antes del siguiente). Para paralelismo real, usa el Python import directo con asyncio.gather. En futuros releases podria añadirse un modo parallel tool execution.