# 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:

```
Authorization: Basic ZGV2a3JvbjpzZWN1cmUxMjM=
```

---

## Solicitud a modelo

### Endpoint

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

### Encabezados

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

### Cuerpo

```json
{
  ...cuerpo de la solicitud propia del modelo invocado
  "_metadata": {
    "request_id": "req-001",
    "invoker": "Un identificador del invocador de la API",
    ... cualquier información adicional
  }
}
```

---

### Respuesta

```json
{
  "success": true,
  "data": {
    ...respuesta propia del modelo invocado
  }
  "_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"
  }
}
```

---

## Gestión de archivos

### 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      |

#### Respuesta

```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.

---

## 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

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.

---