paraconsistent 0.2.4
Blocos de lógica paraconsistente com API simples.
Requires Python: >=3.9
Keywords: logic, paraconsistent, LPA2v, reasoning, fuzzy

# Paraconsistent Lib

Biblioteca Python para construção de redes de raciocínio baseadas em Lógica Paraconsistente Anotada de dois valores (LPA2v).

## 1. Visão Geral

Paraconsistent Lib implementa a Lógica Paraconsistente Anotada de dois valores (LPA2v), permitindo a modelagem de sistemas de raciocínio que lidam naturalmente com inconsistências e incertezas. A biblioteca oferece uma arquitetura modular baseada em blocos lógicos conectáveis, facilitando a composição de redes de inferência complexas.

### Características Principais

- **Implementação completa da LPA2v** com as 12 regiões de estados lógicos
- **Arquitetura modular** baseada em blocos conectáveis
- **Cálculo automático** de graus de certeza, contradição e evidências
- **Type-safe** com suporte completo a type hints Python
- **Zero dependências externas** (apenas biblioteca padrão Python)
- **Cache inteligente** para otimização de performance

## 2. Instalação

### Requisitos

- Python 3.9 ou superior
- Sem dependências externas

### Instalação via pip

```bash
pip install paraconsistent
```

## 3. Fundamentos Teóricos

### 3.1 Lógica Paraconsistente Anotada (LPA2v)

A LPA2v trabalha com dois graus de evidência:

- **μ (mu)**: Grau de evidência favorável, μ ∈ [0, 1]
- **λ (lambda)**: Grau de evidência desfavorável, λ ∈ [0, 1]

A partir destes valores, são calculados:

- **dc (Degree of Certainty)**: dc = μ - λ, dc ∈ [-1, 1]
- **dct (Degree of Contradiction)**: dct = μ + λ - 1, dct ∈ [-1, 1]

### 3.2 Regiões de Estados Lógicos

A LPA2v define 12 regiões no quadrado unitário de anotação (QUPC):

**Estados Extremos:**
- **t (true)**: Alta certeza positiva
- **f (false)**: Alta certeza negativa
- **┬ (Inconsistent)**: Alta contradição
- **┴ (Indeterminate)**: Baixa informação

**Estados de Transição:**
- **Q┬→t**: Quase inconsistente tendendo ao verdadeiro
- **Q┬→f**: Quase inconsistente tendendo ao falso
- **Qt→┬**: Quase verdadeiro tendendo à inconsistência
- **Qf→┬**: Quase falso tendendo à inconsistência
- **Qt→┴**: Quase verdadeiro tendendo à indeterminação
- **Qf→┴**: Quase falso tendendo à indeterminação
- **Q┴→t**: Quase indeterminado tendendo ao verdadeiro
- **Q┴→f**: Quase indeterminado tendendo ao falso

### 3.3 Métricas Complementares

**Distância Radial:**
- **d**: Distância euclidiana ao vértice mais próximo
- **D**: Distância normalizada (clampada em [0, 1])

**Degree of Real Certainty:**
- **dcr**: dcr = (1 - D) × sign(dc)

**Evidências Resultantes:**
- **μE**: Evidência baseada em dc, μE = (dc + 1) / 2
- **μECT**: Evidência de contradição, μECT = (dct + 1) / 2
- **μER**: Evidência real, μER = (dcr + 1) / 2

**Intervalo de Certeza:**
- **φ (phi)**: φ = 1 - |dct|

## 4. Guia de Uso

### 4.1 Criando um Bloco

```python
from paraconsistent.blocks import ParaconsistentBlock

# Criar bloco com valores padrão
bloco = ParaconsistentBlock()
```

### 4.2 Configurando Parâmetros

```python
from paraconsistent.blocks import ParaconsistentBlock

bloco = ParaconsistentBlock()

# Configurar limite de controle de certeza (FtC)
bloco.config.FtC = 0.70
```

### 4.3 Alimentando Entradas

```python
# Definir graus de evidência
bloco.input.mu = 0.80   # Evidência favorável
bloco.input.lam = 0.20  # Evidência desfavorável

# Os cálculos são realizados automaticamente
```

### 4.4 Obtendo Resultados

```python
# Acessar resultados individuais
dc = bloco.complete.dc       # Degree of Certainty
dct = bloco.complete.dct     # Degree of Contradiction
muER = bloco.complete.muER   # Evidência Real
label = bloco.complete.label # Região lógica

# Ou imprimir todos os resultados
bloco.print_complete()
```

### 4.5 Conectando Múltiplos Blocos

```python
from paraconsistent.blocks import ParaconsistentBlock

# Criar rede de dois blocos
b1 = ParaconsistentBlock()
b2 = ParaconsistentBlock()

# Configurar bloco 1
b1.config.FtC = 0.70
b1.input.mu = 0.80
b1.input.lam = 0.30

# Usar saída de b1 como entrada de b2
b2.input.mu = b1.complete.muER
b2.input.lam = 1 - b1.complete.phi

# Resultado propagado automaticamente
print(f"Estado final: {b2.complete.label}")
```

## 5. Referência da API

### 5.1 Construtor

```python
ParaconsistentBlock(
    *,
    mu: float | None = None,
    lam: float | None = None,
    **param_overrides
)
```

**Parâmetros:**
- `mu`: Grau de evidência favorável inicial (opcional)
- `lam`: Grau de evidência desfavorável inicial (opcional)
- `**param_overrides`: Parâmetros de configuração (FtC)

### 5.2 Configuração (config)

| Parâmetro | Tipo | Faixa | Padrão | Descrição |
|-----------|------|-------|--------|-----------|
| FtC | float | [0, 1] | 0.50 | Fator de Tolerância à Certeza (Certainty Control Limit) |

**Nota:** Os valores VSSC, VICC, VSSCT e VICCT são calculados automaticamente a partir de FtC:
- VSSC = FtC
- VICC = -FtC
- VSSCT = 1 - FtC
- VICCT = FtC - 1

### 5.3 Entradas (input)

```python
# Forma 1: Atribuição direta
bloco.input.mu = 0.80
bloco.input.lam = 0.20

# Forma 2: Método funcional
bloco.input(mu=0.80, lam=0.20)
```

Valores são automaticamente clampados no intervalo [0, 1].

### 5.4 Saídas (complete)

| Campo | Tipo | Faixa | Descrição |
|-------|------|-------|-----------|
| mu | float | [0, 1] | Grau de evidência favorável |
| lam | float | [0, 1] | Grau de evidência desfavorável |
| dc | float | [-1, 1] | Degree of Certainty: μ - λ |
| dct | float | [-1, 1] | Degree of Contradiction: μ + λ - 1 |
| d | float | [0, ∞) | Distância radial bruta |
| D | float | [0, 1] | Distância radial normalizada |
| dcr | float | [-1, 1] | Degree of Real Certainty: (1 - D) × sign(dc) |
| phi | float | [0, 1] | Intervalo de certeza: 1 - \|dct\| |
| phiE | float | [0, 1] | Intervalo de certeza (alias de phi) |
| muE | float | [0, 1] | Evidência resultante: (dc + 1) / 2 |
| muECT | float | [0, 1] | Evidência de contradição: (dct + 1) / 2 |
| muER | float | [0, 1] | Evidência real: (dcr + 1) / 2 |
| decision_output | float | {0.0, 0.5, 1.0} | Saída de decisão binária |
| label | str | - | Rótulo da região lógica (t, f, ┬, ┴, etc.) |
| Regions | dict | - | Flags booleanas por região |
| FtC| float | [0, 1] | Echo dos parâmetros usados no cálculo |

**Saída de Decisão (decision_output):**
- 1.0 se μER > FtC (Aceitar como verdadeiro)
- 0.0 se μER < FtC (Rejeitar como falso)
- 0.5 se μER = FtC (Indecisão)

### 5.5 Métodos

```python
# Exportar como dicionário tipado
resultado: Complete = bloco.to_dict()

# Imprimir formatado no console
bloco.print_complete()

# Configurar parâmetro FtC
bloco.set_params(FtC=0.7)
```

## 6. Exemplos Avançados

### 6.1 Sistema de Controle Fuzzy

```python
from paraconsistent.blocks import ParaconsistentBlock

# Criar blocos para temperatura e pressão
temp_block = ParaconsistentBlock()
press_block = ParaconsistentBlock()
decision_block = ParaconsistentBlock()

# Sensor de temperatura (alta = 0.8, baixa = 0.1)
temp_block.input.mu = 0.8
temp_block.input.lam = 0.1

# Sensor de pressão (alta = 0.7, baixa = 0.2)
press_block.input.mu = 0.7
press_block.input.lam = 0.2

# Combinar evidências para decisão
decision_block.input.mu = (temp_block.complete.muER + press_block.complete.muER) / 2
decision_block.input.lam = 1 - decision_block.input.mu

# Avaliar situação
if decision_block.complete.decision_output == 1.0:
    print("Sistema em condição segura")
elif decision_block.complete.decision_output == 0.0:
    print("Alerta: condição crítica detectada")
else:
    print("Situação indefinida - requer análise manual")
```

### 6.2 Análise de Contradições

```python
from paraconsistent.blocks import ParaconsistentBlock

# Cenário: Múltiplas fontes contraditórias
bloco = ParaconsistentBlock()
bloco.config.FtC = 0.6

# Entrada contraditória (alta evidência favorável E desfavorável)
bloco.input.mu = 0.9
bloco.input.lam = 0.8

# Analisar contradição
print(f"Degree of Contradiction: {bloco.complete.dct:.2f}")
print(f"Região Lógica: {bloco.complete.label}")

if "┬" in bloco.complete.label:
    print("⚠️ Inconsistência detectada - revisar fontes de informação")
```

## 7. Arquitetura

### 7.1 Estrutura de Módulos

```
paraconsistent/
├── blocks/
│   └── block.py           # Classe ParaconsistentBlock
├── core/
│   ├── config.py          # Configurações e validação
│   ├── engine.py          # Motor de cálculo
│   ├── metrics.py         # Métricas geométricas
│   ├── labels.py          # Classificação de regiões
│   └── types.py           # Type definitions
└── __init__.py
```

### 7.2 Fluxo de Cálculo

1. **Entrada**: Validação e clamping de μ e λ
2. **Graus Principais**: Cálculo de dc e dct
3. **Geometria**: Cálculo de d, D e dcr
4. **Evidências**: Cálculo de μE, μECT, μER e φ
5. **Decisão**: Comparação de μER com FtC
6. **Classificação**: Identificação da região lógica

### 7.3 Cache e Performance

O sistema implementa cache inteligente que invalida automaticamente ao alterar entradas ou parâmetros, garantindo consistência sem sacrificar performance.

## 8. Validação e Testes

A biblioteca foi validada contra casos de teste padrão da literatura, com taxa de acerto superior a 97% em 37 casos de teste independentes.

## 9. Licença

MIT License

Copyright (c) 2025

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

## 10. Contribuindo

Contribuições são bem-vindas! Por favor, abra uma issue ou pull request no repositório GitHub.

## 11. Suporte

- **Repositório**: https://github.com/dirgogoo/Paraconsistent-Lib
- **PyPI**: https://pypi.org/project/paraconsistent/
- **Issues**: https://github.com/dirgogoo/Paraconsistent-Lib/issues