npm package: @marxito/transcription-ai
Description: Modulo de transcripcion de audio con IA usando Google Gemini - Soporta chunking, rate limiting, entity extraction y quality analysis
Author: marxito
Latest version: 1.0.1

# @centinela/transcription-ai

Modulo de transcripcion de audio con IA usando Google Gemini. Reutilizable para multiples proyectos con soporte para diferentes API Keys.

## Caracteristicas

- Transcripcion de audio usando Gemini AI
- Soporte para multiples formatos: MP3, WAV, M4A, OGG, FLAC, WebM, AAC
- Procesamiento con IA para extraccion de entidades
- Rate limiting inteligente con queue
- Soporte para diferentes tiers de Gemini
- TypeScript nativo

## Instalacion

```bash
npm install @centinela/transcription-ai
# o
yarn add @centinela/transcription-ai
```

## Uso Basico

```typescript
import { TranscriptionClient } from '@centinela/transcription-ai';

// Crear cliente
const client = new TranscriptionClient({
  projectId: 'mi-proyecto',
  apiKey: process.env.GEMINI_API_KEY!,
  options: {
    tier: 'free',        // 'free' | 'level1' | 'level2' | 'level3'
    logLevel: 'info'     // 'debug' | 'info' | 'warn' | 'error' | 'silent'
  }
});

// Inicializar
await client.initialize();

// Transcribir desde archivo
const result = await client.transcribe({
  source: '/path/to/audio.mp3'
});

console.log(result.text);
```

## Transcripcion con IA

```typescript
const result = await client.transcribe({
  source: audioBuffer,
  mimeType: 'audio/mp3',
  aiProcessing: {
    enabled: true,
    context: 'incident',      // 'incident' | 'investigation' | 'evidence' | 'victim' | 'general'
    extractEntities: true,
    formatText: true,
    generateSuggestions: true
  }
});

// Resultado
console.log(result.text);              // Texto transcrito
console.log(result.formattedText);     // Texto formateado por IA
console.log(result.entities);          // Entidades extraidas
console.log(result.suggestions);       // Sugerencias de la IA
console.log(result.metadata);          // Duracion, tokens, costo, etc.
```

## Estimacion de Costos

```typescript
const estimate = await client.estimate({
  source: '/path/to/audio.mp3'
});

console.log(estimate.duration);        // Duracion en segundos
console.log(estimate.tokens);          // Tokens estimados
console.log(estimate.estimatedCost);   // Costo estimado en USD
console.log(estimate.requiresChunking); // Si necesita dividirse
```

## Verificar Capacidad

```typescript
const capacity = client.checkCapacity();

console.log(capacity.available);       // Si hay capacidad disponible
console.log(capacity.queuePosition);   // Posicion en cola
console.log(capacity.currentRpm);      // Requests actuales por minuto
console.log(capacity.maxRpm);          // Limite de requests por minuto
```

## Estadisticas de Uso

```typescript
const stats = client.getUsageStats();

console.log(stats.requestsToday);
console.log(stats.tokensToday);
console.log(stats.totalRequests);
console.log(stats.estimatedTotalCost);
```

## Configuracion Multi-Proyecto

```typescript
// Proyecto 1
const centinelaClient = new TranscriptionClient({
  projectId: 'centinela-system',
  apiKey: process.env.GEMINI_KEY_CENTINELA!
});

// Proyecto 2
const otroClient = new TranscriptionClient({
  projectId: 'otro-proyecto',
  apiKey: process.env.GEMINI_KEY_OTRO!
});

// Cada cliente tiene su propio tracking y rate limiting
```

## Limites de Gemini

| Parametro | Valor |
|-----------|-------|
| Duracion maxima | 9.5 horas |
| Tamano inline | 20 MB |
| Tokens por segundo | 32 |

### Rate Limits por Tier

| Tier | RPM | Requisitos |
|------|-----|------------|
| Free | 15 | Cuenta gratuita |
| Level 1 | 60 | Billing activo |
| Level 2 | 120 | >$250 invertidos |
| Level 3 | 300 | >$1,000 invertidos |

## API Reference

### TranscriptionClient

```typescript
new TranscriptionClient(config: TranscriptionClientConfig)

interface TranscriptionClientConfig {
  projectId: string;
  apiKey: string;
  options?: TranscriptionClientOptions;
}

interface TranscriptionClientOptions {
  tier?: 'free' | 'level1' | 'level2' | 'level3';
  rateLimitStrategy?: 'queue' | 'reject' | 'backoff';
  maxConcurrent?: number;
  maxQueueSize?: number;
  timeout?: number;
  logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent';
  model?: string;
}
```

### TranscribeOptions

```typescript
interface TranscribeOptions {
  source: string | Buffer | Uint8Array;
  mimeType?: AudioMimeType;
  language?: string;
  aiProcessing?: AIProcessingOptions;
  customPrompt?: string;
  priority?: number;
}
```

### TranscriptionResult

```typescript
interface TranscriptionResult {
  text: string;
  language: string;
  formattedText?: string;
  entities?: ExtractedEntities;
  suggestions?: string[];
  metadata: TranscriptionMetadata;
}
```

## License

MIT