# 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
{
  "prompt": "¿Cuál es el impacto fiscal de automatizar procesos en ERP V12?",
  "model": "gpt-5",
  "parameters": {
    "temperature": 0.7,
    "max_tokens": 1024,
    "top_p": 1.0,
    "frequency_penalty": 0.0,
    "presence_penalty": 0.0
  },
  "files": [
    {
      "id": "file_abc123",
      "role": "context",
      "type": "pdf"
    },
    {
      "id": "file_xyz789",
      "role": "attachment",
      "type": "csv"
    }
  ],
  "metadata": {
    "request_id": "req-001",
    "user": "emmanuel",
    "timestamp": "2025-09-22T15:59:00Z"
  }
}
```

---

### Respuesta

```json
{
  "response": {
    "text": "La automatización de procesos fiscales en ERP reduce errores humanos y mejora la trazabilidad.",
    "input_tokens": 11,
    "output_tokens": 76,
    "tokens_used": 87,
    "model": "gpt-5",
    "finish_reason": "stop"
  },
  "files": [
    {
      "id": "file_abc123",
      "used_as": "context",
      "summary": "Documento PDF sobre automatización fiscal en V12 ERP.",
      "metadata": {
        "filename": "fiscal_erp.pdf",
        "size_bytes": 24576,
        "content_type": "application/pdf"
      }
    }
  ],
  "metadata": {
    "request_id": "req-001",
    "timestamp": "2025-09-22T16:00:00Z",
    "duration_ms": 1420,
    "status": "success"
  },
  "error": {
    "code": "ModelTimeout",
    "message": "El modelo no respondió en el tiempo esperado.",
    "details": "Tiempo límite excedido para gpt-4-mini (3000ms)"
  }
}
```

---

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

---