# HUB AI – Especificación de API

El HUB AI permite interactuar con múltiples modelos de inteligencia artificial a través de una interfaz unificada. Soporta autenticación, envío de prompts, gestión de archivos y trazabilidad completa.

---

## Autenticación

Todos los endpoints requieren autenticación mediante encabezado HTTP básico.

### Encabezado

```
Authorization: Basic {base64(api_key:pwd)}
```

Donde `{base64(api_key:pwd)}` representa la codificación Base64 del par `api_key` y `pwd`, separados por dos puntos.

Ejemplo (con los valores ficticios `mi_api_key` y `mi_password`):

```
Authorization: Basic bWlfYXBpX2tleTptaV9wYXNzd29yZA==
```

---

## Solicitud a modelo

### Endpoint

```
POST https://ai.api.induxsoft.net/hub/{modelo}/
```

### Encabezados

```
Authorization: Basic {base64(api_key:pwd)}
Content-Type: application/json
```

### Cuerpo

El cuerpo usa **el mismo formato para todos los modelos**: el de la API *Responses* de OpenAI (GPT-4.1). Para los modelos de otros proveedores (Claude, Gemini, Gemma, DeepSeek, Kimi, Llama, Mistral, Qwen, Nemotron, etc.), el HUB convierte la solicitud al formato del proveedor y la respuesta de vuelta a ese mismo formato.

```json
{
  "input": [
    { "role": "system", "content": "Eres un asistente contable." },
    { "role": "user", "content": "Resume este texto: ..." }
  ],
  "temperature": 0.2,
  "max_tokens": 2048,
  "text": { "format": { "type": "json_object" } },
  "_metadata": {
    "request_id": "req-001",
    "invoker": "Un identificador del invocador de la API",
    ... cualquier información adicional
  }
}
```

Campos del cuerpo:

| Campo | Descripción |
|-------|-------------|
| `input` | Lista de mensajes con `role` (`system`, `user`, `assistant`) y `content`. |
| `temperature`, `top_p` | Opcionales. |
| `max_tokens` | Opcional; si se omite, el HUB usa el máximo configurado para el modelo. |
| `text.format.type` | Opcional; `json_object` o `json_schema` para pedir la respuesta en JSON. |
| `_metadata` | Opcional; datos de trazabilidad del invocador. |

`{modelo}` es el identificador de un modelo habilitado para la clave de API, por ejemplo `openai-gpt-4.1`, `openai-gpt-5-mini`, `claude-sonnet-4.6`, `gemini-2.5-flash` o `deepseek-chat-3.2`.

---

### Respuesta

```json
{
  "success": true,
  "data": {
    ...respuesta en el formato de la API Responses de OpenAI
  }
  "_metadata":
  {
    "request_id":"El identificador de la solicitud (que se ha proporcionado o bien que se ha generado),
    "start":"Fecha y hora de inicio de la solicitud",
    "end":"Fecha y hora de finalización de la solicitud"
  }
}
```

---

### Respuesta de error

```json
{
  "success": 0,
  "code": 401,
  "message": "No autorizado."
}
```

`code` indica el error: `401` (credenciales ausentes o incorrectas, o clave sin ese modelo habilitado), `503` (el modelo no respondió después de los reintentos) u otro, según el proveedor. El HUB intenta hasta 3 veces la solicitud al proveedor y espera hasta 5 minutos cada respuesta.

---

## Gestión de archivos

> **Disponibilidad (revisado el 2026-10-19):** solo **subir** y **eliminar** archivos están implementados, y solo en los modelos de OpenAI (`openai-gpt-4.1`, `openai-gpt-4.1-mini`, `openai-gpt-5`, `openai-gpt-5-mini`, `openai-gpt-5.2`, `openai-gpt-5.2-mini`). **Descargar, consultar metadatos y listar archivos todavía no devuelven datos** en ningún modelo.

### Subir archivo

#### Endpoint

```
POST https://ai.api.induxsoft.net/hub/{modelo}/files
```

#### Encabezados

```
Authorization: Basic {base64(api_key:pwd)}
Content-Type: multipart/form-data
```

#### Campos

| Campo     | Tipo             | Descripción                                               |
|-----------|------------------|-----------------------------------------------------------|
| `file`    | archivo           | Archivo a subir                                           |
| `role`    | texto             | `"context"`, `"attachment"`, `"reference"`               |
| `tags`    | texto             | Lista separada por comas: `"fiscal,erp,devkron"`         |
| `metadata`| JSON (opcional)  | Información adicional (usuario, sesión, etc.)            |
| `docid`   | texto             | Identificador conocido para trazabilidad documental      |

Si la solicitud no puede llevar el encabezado `Authorization`, al subir archivos se acepta el parámetro `?auth={base64(api_key:pwd)}` codificado para URL. No se recomienda: la credencial queda en las bitácoras de los servidores.

#### Respuesta

La implementación actual devuelve en `data` el objeto de archivo del proveedor (OpenAI); su `id` es el que se usa para eliminarlo. La estructura siguiente es la prevista:

```json
{
  "id": "file_abc123",
  "docid": "doc_erp_2025",
  "model": "gpt-5",
  "filename": "fiscal_erp.pdf",
  "size_bytes": 24576,
  "content_type": "application/pdf",
  "role": "context",
  "tags": ["fiscal", "erp", "devkron"],
  "uploaded_at": "2025-09-22T16:18:00Z",
  "status": "stored"
}
```

---

### Descargar archivo

#### Endpoint

```
GET https://ai.api.induxsoft.net/hub/{modelo}/files/{file_id | docid}
```

Devuelve el archivo indicado.

---

### Consultar metadatos de archivo

#### Endpoint

```
GET https://ai.api.induxsoft.net/hub/{modelo}/file-metadata/{file_id | docid}
```

Devuelve los metadatos del archivo como JSON.

---

### Listar últimos archivos

#### Endpoint

```
GET https://ai.api.induxsoft.net/hub/{modelo}/files/
```

Devuelve los metadatos de los últimos 100 archivos cargados por la clave de API autenticada.

---

### Eliminar archivo

#### Endpoint

```
DELETE https://ai.api.induxsoft.net/hub/{modelo}/files/{file_id | docid}
```

Elimina el archivo indicado en el proveedor. `POST https://ai.api.induxsoft.net/hub/{modelo}/files/{file_id}/` tiene el mismo efecto.

---

## Consideraciones de seguridad

- Todos los endpoints requieren autenticación vía `Authorization: Basic`.
- Cada archivo puede asociarse a un `docid` para trazabilidad externa.
- Los modelos pueden validar tipos de archivo y roles antes de procesarlos.

---

## Obtener lista de modelos disponibles

> **Obsoleto / no disponible (revisado el 2026-10-19):** este servicio no está implementado. `GET https://ai.api.induxsoft.net/hub/` responde con error `401` aunque las credenciales sean válidas, porque la autenticación exige un modelo en la ruta. La descripción siguiente se conserva como referencia.

Este servicio permite consultar los modelos de IA habilitados en el HUB, junto con sus atributos relevantes y una descripción de su idoneidad para distintos tipos de tareas.

### Autenticación requerida

Este endpoint requiere autenticación básica.

#### Encabezado

```
Authorization: Basic {base64(api_key:pwd)}
```

---

### Solicitud

#### Endpoint

```
GET https://ai.api.induxsoft.net/hub/
```

---

### Respuesta

```json
[
  {
    "id": "gpt-5",
    "name": "GPT-5",
    "type": "generative",
    "max_input_tokens": 4096,
    "max_output_tokens": 3072,
    "supports_files": true,
    "supports_semantics": true,
    "description": "Modelo de lenguaje avanzado ideal para generación de texto complejo, razonamiento profundo y tareas multilingües. Recomendado para documentación técnica, análisis fiscal y agentes conversacionales."
  },
  {
    "id": "gpt-4-mini",
    "name": "GPT-4 Mini",
    "type": "generative",
    "max_input_tokens": 2048,
    "max_output_tokens": 3072,
    "supports_files": true,
    "supports_semantics": false,
    "description": "Versión ligera de GPT-4, optimizada para respuestas rápidas y tareas de bajo costo. Ideal para asistentes rápidos, resúmenes y respuestas estructuradas."
  },
  {
    "id": "gpt-4.1",
    "name": "GPT-4.1",
    "type": "generative",
    "max_input_tokens": 4096,
    "max_output_tokens": 3072,
    "supports_files": true,
    "supports_semantics": true,
    "description": "Modelo robusto para generación de contenido técnico, análisis contextual y flujos conversacionales auditables. Compatible con archivos adjuntos y prompts enriquecidos."
  },
  {
    "id": "llama-4-maverick",
    "name": "LLaMA 4 Maverick",
    "type": "generative",
    "max_input_tokens": 3072,
    "max_output_tokens": 3072,
    "supports_files": true,
    "supports_semantics": false,
    "description": "Modelo open-source de alto rendimiento, ideal para entornos privados, despliegues locales y tareas personalizadas. Recomendado para desarrolladores que requieren control total."
  },
  {
    "id": "bert",
    "name": "BERT",
    "type": "extractive",
    "max_input_tokens": 3072,
    "max_output_tokens": 3072,
    "supports_files": true,
    "supports_semantics": false,
    "description": "Modelo orientado a extracción de información, clasificación y análisis de texto. Ideal para detección de entidades, búsqueda semántica y tareas de NLP estructurado."
  }
]
```

---

### Consideraciones

- La respuesta está limitada a los modelos habilitados para la clave API autenticada.
- Cada modelo incluye atributos técnicos (`type`, `max_input_tokens`,`max_output_tokens`, `supports_files`, `supports_semantics`) y una descripción funcional.
- Este servicio puede ser usado para construir interfaces dinámicas, validadores de compatibilidad o asistentes de selección de modelo.

---