@chicane-ai/core

Core da ferramenta Chicane para proteção de IA. Fornece a base para criação de validadores e sistemas de proteção para aplicações de inteligência artificial.

🚀 Instalação

npm install @chicane-ai/core

🎯 Uso Básico

import { SafetyCar, OnFailAction } from '@chicane-ai/core';

// Criar uma instância do SafetyCar
const chicane = new SafetyCar();

// Adicionar validadores
chicane.use(validator, options, OnFailAction.EXCEPTION);

// Validar dados
const result = chicane.validate(data);

📦 Componentes Principais

SafetyCar

A classe principal para gerenciar validadores e executar validações.

import { SafetyCar } from '@chicane-ai/core';

const chicane = new SafetyCar();

// Adicionar um validador
chicane.use(validator, options, onFailAction);

// Adicionar múltiplos validadores
chicane.useMany(
  { validator: validator1, config: config1 },
  { validator: validator2, config: config2 }
);

// Validar dados
const result = chicane.validate(data);

// Limpar validadores
chicane.clear();

// Obter configuração atual
const config = chicane.getConfig();

OnFailAction

Enum que define as ações a serem tomadas quando uma validação falha:

• EXCEPTION: Lança uma exceção
• FIX: Tenta corrigir o valor automaticamente
• FILTER: Remove o valor inválido (retorna null)
• REFRAIN: Coleta os erros mas não interrompe o fluxo

import { OnFailAction } from '@chicane-ai/core';

// Exemplo de uso
chicane.use(validator, options, OnFailAction.EXCEPTION);

BoxValidator

Interface que todos os validadores devem implementar:

import { BoxValidator, ValidationResult } from '@chicane-ai/core';

class MeuValidador implements BoxValidator {
  name = 'MeuValidador';

  validate(value: any, options?: any): ValidationResult {
    // Implementar lógica de validação
    if (/* condição válida */) {
      return { valid: true };
    } else {
      return {
        valid: false,
        errors: ['Mensagem de erro']
      };
    }
  }
}

ValidationResult

Interface que define o resultado de uma validação:

interface ValidationResult {
  valid: boolean;           // Se a validação passou
  errors?: string[];        // Lista de erros (se houver)
  fixedValue?: any;         // Valor corrigido (se aplicável)
}

🔧 Exemplos

Validação Básica

import { SafetyCar, OnFailAction } from '@chicane-ai/core';

const chicane = new SafetyCar();

// Validar dados
try {
  const result = chicane.validate("dados para validar");
  console.log("Validação passou:", result.valid);
} catch (error) {
  console.error("Validação falhou:", error.message);
}

Múltiplos Validadores

import { SafetyCar, OnFailAction } from '@chicane-ai/core';

const chicane = new SafetyCar()
  .use(validator1, options1, OnFailAction.REFRAIN)
  .use(validator2, options2, OnFailAction.EXCEPTION);

const result = chicane.validate(data);

Validação com Bandeira Verde (Green Flag)

import { SafetyCar } from '@chicane-ai/core';

const chicane = new SafetyCar();

// Validar e executar callback apenas se passar (Bandeira Verde)
const result = await chicane.greenFlag(
  data,
  async (validatedData) => {
    // Este callback só é executado se a validação passar
    return await llmApi.generateResponse("prompt", validatedData);
  }
);

Validação com Callbacks de Sucesso e Erro

const result = await chicane.validateWithCallbacks(
  data,
  // Callback de sucesso
  async (validatedData) => {
    return await llmApi.generateResponse("prompt", validatedData);
  },
  // Callback de erro (opcional)
  async (errors) => {
    console.log("Validação falhou:", errors);
    return "Dados inválidos";
  }
);

🏗️ Arquitetura

O core do Chicane é projetado para ser:

• Modular: Cada validador é independente
• Extensível: Fácil adição de novos validadores
• Flexível: Múltiplas ações de falha
• Type-safe: Totalmente tipado com TypeScript

📦 Boxes Disponíveis

• @chicane-ai/box-regex-match: Validação com expressões regulares
• @chicane-ai/box-json-validation: Validação de JSON e schemas

🤝 Contribuindo

Para contribuir com o core:

1. Fork o repositório
2. Crie uma branch para sua feature
3. Implemente suas mudanças
4. Adicione testes
5. Abra um Pull Request

📄 Licença

MIT License

🔗 Links

• Documentação completa
• Issues
• Discord