La API estará disponible en `http://localhost:8000`.

Para la ejecución de transformación local, Redis y el worker de transformación también deben estar ejecutándose. Solo Redis no es suficiente.

Iniciar Redis:```bash
docker run -d --name ogi-redis -p 6379:6379 redis:7-alpine

Si ves `Job queue not available` o `Redis not available`, verifica que:

- `OGI_REDIS_URL` apunta a `redis://localhost:6379/0` para ejecuciones locales en el host
- el backend se reinició después de que Redis se iniciara
- el proceso worker separado está en ejecución
- no estás usando el nombre de host exclusivo de Docker `redis` fuera de Docker Compose

Si ejecutas el backend contra PostgreSQL (`OGI_USE_SQLITE=false`), el inicio aplicará automáticamente las migraciones de Alembic antes de servir las solicitudes. Las implementaciones de Docker hacen lo mismo en el entrypoint del contenedor del backend.

Las ejecuciones de AI Investigator son procesadas por otro worker separado:```bash
cd backend
uv run python -m ogi.agent.run_worker

Abre http://localhost:5173. Eso es todo.

### AI Investigator

AI Investigator es un flujo de trabajo opcional respaldado por un proveedor que puede planificar secuencias de transformación, solicitar aprobaciones y resumir el progreso de la investigación dentro del espacio de trabajo.

- Abre la pestaña `AI Investigator` dentro de un proyecto
- Configura un proveedor y un modelo en el diálogo de configuración del investigador
- Almacena las claves API del proveedor en `API Keys`
- Ejecuta el proceso separado `agent-worker` junto al backend

La implementación actual soporta configuración de proveedor por usuario y un trabajador dedicado que ejecuta pasos de investigación de forma independiente del servidor API principal.

### CLI

Dos formas compatibles de ejecutar la CLI:

**Recomendado** (sin necesidad de activación):```bash
cd backend
uv sync
uv run ogi --help

## Docker

### Desarrollo```bash
cp .env.example .env
docker compose up

Use el archivo de compose de producción solo cuando ya tenga una instancia de PostgreSQL accesible y haya configurado `OGI_DATABASE_URL` en consecuencia:```bash
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

Para eliminar capacidades específicas en un despliegue local-first:```env
OGI_TRANSFORM_SETTING_MAX_OVERRIDES=max_results=none,max_urls=none,max_links=none,max_content_chars=none

### Categorías de Transformaciones Integradas

| Categoría      | Ejemplos                                        |
| -------------- | ----------------------------------------------- |
| DNS            | A, AAAA, MX, NS, CNAME registros                |
| IP y ASN       | GeoIP, IP inversa, información ASN              |
| SSL/TLS        | Transparencia de certificados, SSL labs         |
| Correo electrónico | Validación de servidor de correo, verificaciones de brechas |
| Web            | WHOIS, información de dominio, extracción web   |
| Social         | Enumeración de nombres de usuario, perfiles sociales |
| Hash           | Consultas MD5, SHA1, SHA256                     |
| Ubicación      | Geocodificación, clima, datos ASN cercanos      |

### Tipos de Entidad Compatibles

`Person` • `Username` • `Domain` • `IPAddress` • `EmailAddress` • `PhoneNumber` • `Organization` • `URL` • `SocialMedia` • `Hash` • `Document` • `Location` • `ASNumber` • `Network` • `MXRecord` • `NSRecord` • `Nameserver` • `SSLCertificate` • `Subdomain` • `HTTPHeader`

### Construyendo Tus Propias Transformaciones

¿Quieres construir las tuyas? Consulta la [guía de contribución](https://github.com/opengraphintel/ogi-transforms/blob/main/CONTRIBUTING.md).

Si tu transformación necesita credenciales de servicio externas, decláralas en `api_keys_required`. No almacenes secretos en la configuración de la transformación. OGI los gestiona bajo `API Keys`, y los plugins que usan secretos se consideran código privilegiado.

Si tu transformación expone configuraciones limitadas como `max_results` o `max_content_chars`, prefiere nombres de configuración estables sobre nombres personalizados únicos cuando sea posible. OGI puede anular centralmente los valores máximos con `OGI_TRANSFORM_SETTING_MAX_OVERRIDES`, lo que ayuda a que las implementaciones en la nube apliquen límites mientras que los usuarios locales pueden eliminarlos.

Cada plugin es un directorio con un manifiesto `plugin.yaml`:```yaml
name: my-transform
version: "1.0.0"
display_name: My Transform
description: What it does
author: Your Name
license: MIT
category: dns
input_types: [Domain]
output_types: [IPAddress]
permissions:
  network: true
  filesystem: false
  subprocess: false

### Configuración

OGI utiliza [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) con soporte para archivos `.env`. Las variables de ejecución/backend tienen el prefijo `OGI_`.

Las configuraciones de tipo lista aceptan:

- Arreglos JSON, por ejemplo `["plugins","../plugins"]`
- cadenas separadas por comas, por ejemplo `plugins,../plugins`

<details>
<summary><strong>Variables de entorno clave</strong></summary>

| Variable                                        | Descripción                                                                                                      | Por defecto                                         |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `OGI_APP_NAME`                                  | Nombre de la aplicación                                                                                          | `OGI`                                               |
| `OGI_HOST`                                      | Host de enlace del backend                                                                                       | `0.0.0.0`                                           |
| `OGI_PORT`                                      | Puerto del backend                                                                                               | `8000`                                              |
| `OGI_CORS_ORIGINS`                              | Orígenes de frontend permitidos                                                                                  | `http://localhost:5173,http://localhost:3000`       |
| `OGI_USE_SQLITE`                                | Usar SQLite en lugar de PostgreSQL                                                                               | `true`                                              |
| `OGI_DB_PATH`                                   | Ruta del archivo de base de datos SQLite                                                                         | `ogi.db`                                            |
| `OGI_DATABASE_URL`                              | Cadena de conexión PostgreSQL                                                                                    | `postgresql://postgres:postgres@localhost:5432/ogi` |
| `OGI_REDIS_URL`                                 | Cadena de conexión Redis para RQ/trabajos                                                                        | `redis://localhost:6379/0`                          |
| `OGI_RQ_QUEUE_NAME`                             | Nombre de la cola para trabajos de transformación                                                                | `transforms`                                        |
| `OGI_TRANSFORM_TIMEOUT`                         | Tiempo de espera por trabajo de transformación en segundos                                                       | `300`                                               |
| `OGI_AGENT_WORKER_POLL_INTERVAL_SEC`            | Intervalo de sondeo para el trabajador del Investigador IA                                                       | `2.0`                                               |
| `OGI_AGENT_CLAIM_TIMEOUT_SEC`                   | Tiempo de espera por reclamo obsoleto para recuperación de pasos del Investigador IA                             | `120`                                               |
| `OGI_AUTO_RUN_MIGRATIONS`                       | Ejecutar automáticamente Alembic al inicio local sin SQLite                                                      | `true`                                              |
| `OGI_RUN_DB_MIGRATIONS`                         | Ejecutar migraciones de BD en el punto de entrada del contenedor                                                 | `false`                                             |
| `OGI_DB_MIGRATION_RETRIES`                      | Número de reintentos de migración en el punto de entrada                                                         | `30`                                                |
| `OGI_DB_MIGRATION_DELAY_SECONDS`                | Retraso entre reintentos de migración en el punto de entrada                                                     | `2`                                                 |
| `OGI_PLUGIN_DIRS`                               | Directorios de búsqueda de plugins                                                                               | `plugins,../plugins`                                |
| `OGI_DEPLOYMENT_MODE`                           | Modo de despliegue (`self-hosted` o `cloud`)                                                                     | `self-hosted`                                       |
| `OGI_CLOUD_BILLING_ENABLED`                     | Activar facturación de Soporte solo en nube y cumplimiento de enfriamiento de transformación                     | `false`                                             |
| `OGI_FREE_TRANSFORM_COOLDOWN_SECONDS`           | Enfriamiento entre ejecuciones de transformador de usuario gratuito en la nube                                  | `1800`                                              |
| `OGI_PAID_TRANSFORM_COOLDOWN_SECONDS`           | Enfriamiento entre ejecuciones de transformador de usuario de pago en la nube                                   | `0`                                                 |
| `OGI_STRIPE_SECRET_KEY`                         | Clave secreta del lado del servidor de Stripe para sesiones de Checkout y portal                                 | sin establecer                                      |
| `OGI_STRIPE_WEBHOOK_SECRET`                     | Secreto de firma de webhook de Stripe                                                                            | sin establecer                                      |
| `OGI_STRIPE_SUPPORTER_PRICE_ID`                 | ID de precio recurrente de Stripe para el plan de Soporte                                                        | sin establecer                                      |
| `OGI_STRIPE_SUPPORTER_AMOUNT_CENTS`             | Monto mostrado para el plan de Soporte                                                                           | `300`                                               |
| `OGI_STRIPE_SUPPORTER_CURRENCY`                 | Moneda mostrada para el plan de Soporte                                                                          | `usd`                                               |
| `OGI_BILLING_SUCCESS_URL`                       | Redirección opcional de éxito de Stripe Checkout                                                                 | derivado de la solicitud                            |
| `OGI_BILLING_CANCEL_URL`                        | Redirección opcional de cancelación de Stripe Checkout                                                           | derivado de la solicitud                            |
| `OGI_BILLING_PORTAL_RETURN_URL`                 | URL de retorno opcional del portal de facturación de Stripe                                                      | derivado de la solicitud                            |
| `OGI_REGISTRY_REPO`                             | Repositorio de GitHub del registro de transformaciones                                                           | `opengraphintel/ogi-transforms`                     |
| `OGI_REGISTRY_CACHE_TTL`                        | TTL de caché del registro en segundos                                                                            | `3600`                                              |
| `OGI_TRANSFORM_SETTING_MAX_OVERRIDES`           | Mapa opcional de anulación máxima global para configuraciones de transformación                                  | vacío                                               |
| `OGI_GITHUB_TOKEN`                              | Token opcional de GitHub para límites de tasa de registro/API                                                    | sin establecer                                      |
| `OGI_SUPABASE_URL`                              | URL del proyecto Supabase                                                                                        | sin establecer                                      |
| `OGI_SUPABASE_ANON_KEY`                         | Clave anónima/pública de Supabase                                                                                | sin establecer                                      |
| `OGI_SUPABASE_SERVICE_ROLE_KEY`                 | Clave de función de servicio de Supabase                                                                         | sin establecer                                      |
| `OGI_SUPABASE_JWT_SECRET`                       | Secreto JWT de Supabase                                                                                          | sin establecer                                      |
| `OGI_SUPABASE_REDIRECT_URL`                     | URL de redirección utilizada por flujos de autenticación del frontend                                            | sin establecer                                      |
| `OGI_ADMIN_EMAILS`                              | Usuarios administradores para gestión de registro/plugins                                                        | sin establecer                                      |
| `OGI_TELEMETRY_ENABLED`                         | Habilitar o deshabilitar telemetría a nivel de instalación                                                       | `true`                                              |
| `OGI_TELEMETRY_LEVEL`                           | Nivel de telemetría (`basic` o `full`)                                                                           | `full`                                              |
| `OGI_API_KEY_ENCRYPTION_KEY`                    | Clave Fernet para almacenamiento cifrado de claves API                                                           | sin establecer pero muy recomendado                 |
| `OGI_API_KEY_INJECTION_ALLOW_COMMUNITY_PLUGINS` | Permitir que plugins comunitarios reciban claves API almacenadas                                                 | `true`                                              |
| `OGI_API_KEY_INJECTION_TRUSTED_TIERS_ONLY`      | Restringir inyección de claves almacenadas solo a niveles de confianza                                           | `false`                                             |
| `OGI_API_KEY_INJECTION_ALLOWED_TIERS`           | Niveles permitidos cuando el modo solo confiable está habilitado                                                 | `official,verified`                                 |
| `OGI_API_KEY_SERVICE_ALLOWLIST`                 | Servicios permitidos opcionales para inyección de claves almacenadas                                             | vacío                                               |
| `OGI_API_KEY_SERVICE_BLOCKLIST`                 | Servicios bloqueados opcionales para inyección de claves almacenadas                                             | vacío                                               |
| `OGI_LLM_PROVIDER`                              | Proveedor predeterminado de respaldo del Investigador IA                                                         | `openai`                                            |
| `OGI_LLM_MODEL`                                 | Modelo predeterminado de respaldo del Investigador IA                                                            | `gpt-4.1-mini`                                      |
| `OGI_EXPOSE_ERROR_DETAILS`                      | Incluir detalles internos en respuestas 500                                                                      | `false`                                             |
| `OGI_SANDBOX_ENABLED`                           | Habilitar modo de ejecución sandbox                                                                              | `false`                                             |
| `OGI_SANDBOX_TIMEOUT`                           | Tiempo de espera del sandbox en segundos                                                                         | `30`                                                |
| `OGI_SANDBOX_MEMORY_MB`                         | Límite de memoria del sandbox en MB                                                                              | `256`                                               |
| `OGI_SANDBOX_ALLOWED_TIERS`                     | Niveles permitidos en modo sandbox en la nube                                                                    | `official,verified`                                 |
| `OGI_BOOT_REQUIREMENTS_ENABLE`                  | Habilitar instalación de dependencias de plugins al inicio                                                       | `true`                                              |
| `OGI_BOOT_REQUIREMENTS_FILE`                    | Ruta del archivo de requisitos de inicio                                                                         | `/app/plugins/requirements.txt`                     |
| `OGI_BOOT_LOCK_FILE`                            | Ruta del archivo de bloqueo de inicio                                                                            | `/app/plugins/ogi-lock.json`                        |
| `OGI_BOOT_REQUIREMENTS_STRICT`                  | Fallar al inicio si faltan requisitos de plugins                                                                 | `false`                                             |
| `OGI_BOOT_REQUIREMENTS_CACHE_DIR`               | Directorio temporal/caché para generación de requisitos de inicio                                                | `/tmp/ogi-boot`                                     |
| `OGI_FRONTEND_PORT`                             | Mapeo de puerto del frontend Docker local                                                                        | `3000`                                              |
| `OGI_IMAGE_TAG`                                 | Etiqueta de imagen de producción para despliegues compose/Coolify                                                | `latest`                                            |
| `OGI_BACKEND_IMAGE`                             | Anulación opcional de imagen del backend                                                                         | `ghcr.io/khashashin/ogi-backend`                    |
| `OGI_WORKER_IMAGE`                              | Anulación opcional de imagen del worker. Por defecto usa la imagen del backend porque worker y backend comparten la misma compilación de imagen. | `ghcr.io/khashashin/ogi-backend`                    |
| `OGI_FRONTEND_IMAGE`                            | Anulación opcional de imagen del frontend                                                                        | `ghcr.io/khashashin/ogi-frontend`                   |
| `OGI_CLI_BEARER_TOKEN`                          | Token bearer opcional de CLI para backends con autenticación                                                     | sin establecer                                      |

Consulta [`.env.example`](https://github.com/khashashin/ogi/blob/HEAD/.env.example) para la lista completa.

</details>

## Desarrollo

### Ejecutar Pruebas```bash
# Backend
cd backend
OGI_DB_PATH=":memory:" OGI_USE_SQLITE=true uv run pytest

# Frontend
cd frontend
pnpm test

### Pipeline de CI

El [flujo de trabajo de CI](https://github.com/khashashin/ogi/blob/HEAD/.github/workflows/ci.yml) se ejecuta en cada pull request:

- **Backend:** ruff lint, mypy type check, pytest
- **Frontend:** vitest, eslint, vite build

## Contribuciones

¡Las PRs son bienvenidas! Si encuentras un error o tienes una idea, [abre un issue](https://github.com/khashashin/ogi/issues).

Para nuevas transformaciones, contribuye a [ogi-transforms](https://github.com/opengraphintel/ogi-transforms).

### Primeros pasos

1. Haz un fork del repositorio
2. Crea una rama de funcionalidad (`git checkout -b feature/mi-funcionalidad`)
3. Realiza tus cambios
4. Ejecuta las pruebas y el linting
5. Envía un pull request

## Uso legal y responsable

OGI es una herramienta de OSINT y análisis de grafos de propósito general. **Eres el único responsable de cómo la utilizas.** Consulta [LEGAL.md](https://github.com/khashashin/ogi/blob/HEAD/LEGAL.md) para el aviso legal completo.

- **Cumple con los Términos de Servicio de terceros.** Las transformaciones que consultan servicios externos (DNS, WHOIS, web scraping, búsquedas de nombres de usuario, etc.) deben usarse de acuerdo con los ToS de esos servicios. La consulta automatizada o masiva de sitios que lo prohíban puede violar sus términos.
- **Respeta la ley de protección de datos.** Si estás en la UE o procesas datos de residentes de la UE, el RGPD se aplica a ti como responsable del tratamiento. La recopilación, almacenamiento o procesamiento de datos personales (nombres, direcciones de correo electrónico, direcciones IP, etc.) requiere una base legal. OGI en sí mismo no almacena datos más allá de tu instancia local; eres responsable de lo que recopilas y retienes.
- **Úsalo solo con fines legales.** OGI está diseñado para la investigación de seguridad legítima, investigaciones, inteligencia de amenazas y uso educativo. No lo uses para acosar a personas, realizar accesos no autorizados o violar la ley aplicable.
- **Compatibilidad de formatos de archivo.** OGI admite la importación del formato de intercambio de grafos MTGX. Esto se proporciona puramente para la interoperabilidad de datos y no implica ninguna afiliación ni respaldo por parte de los creadores de herramientas que utilizan este formato.

> **Descargo de responsabilidad:** OGI se proporciona "tal cual" sin garantía de ningún tipo. Los autores no son responsables por ningún uso indebido o daños derivados del uso de este software.

## Licencia

Este proyecto está licenciado bajo la [GNU Affero General Public License v3.0](https://github.com/khashashin/ogi/blob/HEAD/LICENSE).

---

<div align="center">

**[Reportar un error](https://github.com/khashashin/ogi/issues) &bull; [Solicitar una función](https://github.com/khashashin/ogi/issues) &bull; [Discusiones](https://github.com/opengraphintel/ogi-transforms/discussions)**

Hecho con 💜 por la comunidad OGI

</div>