Metadata-Version: 2.4
Name: lio-lang
Version: 0.1.0
Summary: Structured key:value protocol for machine-to-machine LLM communication
Author: Estevao
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/estevaofon/lio-lang
Project-URL: Repository, https://github.com/estevaofon/lio-lang
Project-URL: Issues, https://github.com/estevaofon/lio-lang/issues
Project-URL: Documentation, https://github.com/estevaofon/lio-lang#readme
Keywords: llm,prompt-engineering,agents,anthropic,openai,claude
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40.0; extra == "anthropic"
Provides-Extra: benchmarks
Requires-Dist: anthropic>=0.40.0; extra == "benchmarks"
Requires-Dist: python-dotenv>=1.0.0; extra == "benchmarks"
Requires-Dist: pydantic>=2.0; extra == "benchmarks"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: anthropic>=0.40.0; extra == "dev"
Requires-Dist: python-dotenv>=1.0.0; extra == "dev"
Requires-Dist: pydantic>=2.0; extra == "dev"
Dynamic: license-file

# lio-lang

Protocolo estruturado key:value para comunicacao maquina-a-maquina com LLMs.
Substitui a prosa que o modelo produz entre tool calls e em respostas
finais por um formato compacto parecido com JSON, voltado para outputs
que serao consumidos por codigo, agentes ou automacao em vez de lidos
por humanos.

```python
import lio

prompt = lio.system_prompt(mode="agentic", language="en")
report = lio.validate(model_text)           # compliance check
natural = lio.render(lio_text)               # LIO -> natural for display
metrics = lio.measure(                       # cost/savings math
    natural_input_tokens=582, natural_output_tokens=25378,
    lio_input_tokens=4311, lio_output_tokens=5488,
    model="claude-opus-4-6",
)
```

Sem dependencias obrigatorias. Licenca Apache 2.0. Python 3.11+.

---

## Instalacao

```bash
pip install lio-lang                    # core, zero dependencias
pip install lio-lang[anthropic]         # com wrapper da SDK Anthropic
pip install lio-lang[benchmarks]        # com deps para rodar os benchmarks

# Ou com uv
uv sync
uv sync --extra anthropic
uv sync --extra benchmarks
```

---

## Quickstart

```python
import anthropic
import lio

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    system=lio.system_prompt(mode="single_shot", language="en"),
    messages=[{"role": "user", "content": "Write a Python prime filter function"}],
)

raw_text = "".join(b.text for b in response.content if b.type == "text")

# Check the response is compliant LIO
report = lio.validate(raw_text)
print(f"compliant: {report.compliant} (score {report.score})")

# Convert LIO to natural language for human display (no extra API call)
print(lio.render(raw_text, language="en"))
```

Exemplos rodaveis em `examples/`:

```bash
# Exercita toda a API publica, funciona offline e online
uv run examples/quickstart.py                       # sem API key: so offline
uv run --extra anthropic examples/quickstart.py     # com API key: online tambem

# Compara baseline natural vs LIO roundtrip lado a lado
uv run --extra anthropic examples/full_flow.py --prompt "Faca uma funcao de ordenacao"
uv run --extra anthropic examples/full_flow.py --prompt "Write a debounce function" --language en
```

---

## API publica

| Funcao | Proposito |
|---|---|
| `lio.system_prompt(mode, language)` | Retorna a string do system prompt LIO. `mode="agentic"` (multi-turno com tools) ou `"single_shot"`. `language="en"` ou `"pt"`. |
| `lio.validate(text)` | Checa se um text block e LIO valido. Retorna `ComplianceReport(compliant, score, reasons)`. |
| `lio.render(lio_text, language)` | Converte LIO de volta para linguagem natural para display. Rule-based, zero chamadas de API. Fallback seguro retorna o input inalterado. |
| `lio.measure(...)` | Calcula economia de custo a partir de contagens pareadas de tokens. Retorna `EconomyMetrics` com custo, economia percentual, breakdown de input/output. |
| `lio.middleware.wrap_call` | Decorator que injeta o system prompt LIO em qualquer funcao de chamada LLM e opcionalmente roda um callback de telemetria. |

### Exemplo de middleware

```python
import lio
from lio.middleware import wrap_call

def telemetry(response):
    text = "".join(b.text for b in response.content if b.type == "text")
    r = lio.validate(text)
    print(f"[lio] compliance={r.score:.2f}")

@wrap_call(mode="agentic", language="en", on_response=telemetry)
def call_claude(messages, **kwargs):
    return client.messages.create(
        model="claude-opus-4-6",
        max_tokens=16000,
        messages=messages,
        **kwargs,
    )

# Cada chamada vai automaticamente:
#  1. receber o system prompt LIO injetado
#  2. ser validada via callback
response = call_claude(messages=[{"role": "user", "content": "..."}])
```

---

## Filosofia

**LIO estrutura informacao, nao comprime.**

O objetivo nao e "economizar tokens a qualquer custo". E transferir a
mesma informacao que linguagem natural transferiria, eliminando o
overhead de apresentacao: prosa, markdown, pedagogia, cortesia,
decoracao visual.

O que cai fora sao as sobras de linguagem natural, nao os dados.
Detalhes tecnicos que perderiam funcionalidade se abreviados
(paths absolutos, identificadores exatos, valores de config, schemas)
sao preservados. Quando a resposta precisa de valores que o consumidor
vai substituir, usa-se placeholders explicitos `<REPLACE:nome>` em vez
de tentar comprimir com truques que colidem com sintaxe da linguagem
alvo.

A analogia correta e com JSON, nao com compressao lossy:

> LIO esta para prosa assim como JSON esta para XML-verboso: mesma
> informacao, sem a gordura de apresentacao. JSON nao e "compressao
> lossy de XML"; e uma estruturacao diferente da mesma informacao.
> LIO tem a mesma relacao com a prosa de LLM.

Consequencias praticas:

- Uma resposta LIO pode ser longa se a informacao exige.
- Use quantos campos forem necessarios para manter precisao tecnica.
- Alternativas validas sao preservadas via campo `variant`.
- O modelo mantem liberdade de planejamento, nao e constrangido a
  "escolher uma resposta e descartar as outras".

---

## Sintaxe

### Gramatica minima

```
field        = key ':' value
value        = escalar | '[' lista ']' | '{' objeto '}' | '<REPLACE:' nome '>'
text_block   = sequencia de fields, separados por espaco ou newline
```

Escalares sao literais. Listas usam virgula. Objetos usam virgula entre pares.

### Campos reservados

Uma letra para a estrutura base:

| Campo | Uso |
|---|---|
| `T` | task type |
| `O` | object / target |
| `P` | params |
| `C` | context |
| `F` | expected format |
| `X` | constraints |
| `S` | status (`ok`, `err`, `partial`) |
| `R` | result |
| `D` | data |
| `W` | warning |
| `E` | error |
| `Q` | query |
| `N` | count |

Palavras-chave para semantica adicional:

| Campo | Uso |
|---|---|
| `step` | acao atual (loops agenticos) |
| `next` | proxima acao |
| `fix` | correcao proposta |
| `issues` | lista de problemas encontrados |
| `causes` | lista de causas possiveis |
| `variant` | resposta alternativa valida |
| `note` | observacao nao obvia |
| `code` | bloco de codigo (passa intacto) |
| `steps` | sequencia de passos |

Voce pode introduzir campos novos quando fizer sentido.

### Placeholders explicitos

Quando a resposta precisa de valores que o consumidor deve substituir,
use `<REPLACE:nome_descritivo>`. Por que nao outras opcoes:

- `$variavel` ou `${variavel}` colidem com bash, nginx, make
- `{{variavel}}` colide com Jinja, Mustache, Go templates
- `__variavel__` fragil, nao se destaca
- `<REPLACE:nome>` angle brackets sao slot universal, `REPLACE` e
  explicito, nenhuma linguagem mainstream usa esse token literal

Exemplo (config nginx com SSL):

```
S:ok R:nginx_config
code:{
server {
    listen 443 ssl http2;
    server_name <REPLACE:your_domain>;
    ssl_certificate /etc/letsencrypt/live/<REPLACE:your_domain>/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/<REPLACE:your_domain>/privkey.pem;
    location / { proxy_pass http://localhost:3000; }
}
}
W:run_certbot_first->certbot --nginx -d <REPLACE:your_domain>
```

### O que LIO nao tem

O mesmo que JSON nao tem: markdown headers, tabelas, listas bullet,
emoji decorativo, blocos de citacao, negrito/italico, preambulo
("Aqui esta..."), cortesia ("Espero que ajude"), ou prosa explicativa
redundante com o conteudo.

Codigo dentro de `code:{}` passa intacto, pode conter qualquer sintaxe
da linguagem alvo.

---

## Quando usar LIO

Use onde o consumidor da resposta **nao e um humano**, ou onde a
resposta sera processada por codigo antes de chegar em humano.

**Casos ideais:**
- Pipelines agentic (agente LLM agente) - nenhum humano le o intermediario
- Workflows automatizados (n8n, Make, Zapier)
- RAG chains - query, retrieve, LLM, resposta estruturada downstream
- Multi-agent systems onde agentes conversam entre si
- Batch processing - milhares de chamadas identicas em formato
- Coding agent plugins - raciocinio intermediario entre tool calls

**Nao use para:**
- Chat direto com humano - o humano precisa ler a resposta
- Tarefas criativas (escrita, brainstorm) - a verbosidade e o produto
- Educacao e explicacoes - tokens de explicacao sao o produto
- Respostas onde a prosa **e** o valor (emails, documentacao)

---

## Padroes de integracao

### 1. Injecao direta do system prompt

O mais simples. Funciona com qualquer SDK:

```python
import anthropic
import lio

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    system=lio.system_prompt(mode="agentic", language="en"),
    messages=[{"role": "user", "content": "..."}],
)
```

### 2. Middleware decorator

Se voce ja tem uma funcao que chama a LLM, so decora:

```python
import lio
from lio.middleware import wrap_call

@wrap_call(mode="agentic", language="en", on_response=lambda r: print("[lio] ok"))
def call_llm(messages, **kwargs):
    return client.messages.create(
        model="claude-opus-4-6",
        max_tokens=16000,
        messages=messages,
        **kwargs,
    )

response = call_llm(messages=[{"role": "user", "content": "..."}])
```

### 3. Renderizacao para UI

Se o consumidor final e humano, converta LIO de volta para natural
antes de mostrar:

```python
text = "".join(b.text for b in response.content if b.type == "text")
human_view = lio.render(text, language="en")
print(human_view)
```

Transformacao rule-based local, sem chamada de API. Cobre os padroes
comuns (`S:ok code:{...}`, `issues:[...] fix:[...]`, objetos aninhados,
listas) e faz fallback seguro retornando o input inalterado quando nao
reconhece a forma.

---

## Benchmarks

Bateria de 15 tarefas single-shot contra `claude-opus-4-6`, pareando
prompts em linguagem natural com prompts em LIO. Roda com:

```bash
python -m benchmarks.run                 # 15 tarefas, ~$1
python -m benchmarks.multi_turn          # sessao agentic, ~$0.15
python -m benchmarks.fidelity            # LLM-as-judge, ~$0.30
```

### Resultados representativos

| Cenario | Compliance | Fidelidade | Economia custo | Economia output |
|---|---|---|---|---|
| Single-shot, 15 tarefas | 100% | 95% | 69-75% | 79-82% |
| Multi-turn agentic, 3 turnos | 100% | - | 40-55% | 55-73% |
| Roundtrip Fibonacci (example full_flow) | 100% | - | 70-75% | 83-87% |

Compliance e medido pelo validator local (`lio.validate`). Fidelidade
e medida com LLM-as-judge calibrado em `benchmarks/fidelity.py`.
Economia de output varia por categoria:

| Categoria | Economia de output |
|---|---|
| debug | ~70% |
| cfg | ~85% |
| refactor | ~85% |
| code | ~80% |
| analyze | ~65% |

Economia efetiva varia com a proporcao de text vs tool_use no output
total. Para coding agents com uso pesado de tools, a economia por
sessao tipicamente fica entre 30-50%, pois LIO so afeta os text blocks
do modelo - tool_use blocks JSON permanecem identicos.

---

## Limites conhecidos

1. **Economia depende do shape da tarefa.** Tarefas prose-heavy
   (explicacoes, analises, debug) capturam 60-75%. Tarefas
   tool-heavy (coding agents com muito read/write/bash) capturam
   30-50%. Tarefas onde o output e dominado por codigo cru dentro
   de `code:{}` capturam 20-30% (o codigo passa intacto).

2. **Input savings sao frequentemente negativos.** O system prompt
   LIO adiciona ~500 tokens por chamada. Em prompts curtos isso
   domina o input. A economia vem do output, que custa 5x mais
   que input no Opus. Em sessoes longas com historico acumulado,
   input savings vira positivo.

3. **LIO requer modelos inteligentes.** Testado em Opus 4.6 e
   Sonnet 4.6. Nao recomendado para Haiku - o overhead cognitivo
   de seguir o protocolo nao compensa para modelos menores.
   Haiku pode ser usado como decoder LIO->natural barato.

4. **Drift de compliance em prompts-gatilho.** Palavras como
   "relatorio"/"report" no prompt do usuario ativam priors fortes
   para output em markdown. O validator detecta drift (inclui
   detecao de markdown inclusive dentro de `code:{}` blocks), e a
   filosofia "estrutura nao compressao" mitiga, mas vale atencao.

5. **Fidelidade depende de juiz calibrado.** LLM-as-judge pode
   penalizar LIO por "omissoes" que sao na verdade over-delivery
   da resposta natural (info que o usuario nao pediu). O juiz em
   `benchmarks/fidelity.py` e calibrado para ancorar o julgamento
   na pergunta do usuario, nao na resposta natural de referencia.

---

## Estrutura do repositorio

```
lio-lang/
├── lio/
│   ├── __init__.py               # API publica
│   ├── protocol.py               # factory de system prompts
│   ├── validator.py              # compliance checker
│   ├── render.py                 # LIO -> natural (rule-based)
│   ├── metrics.py                # calculo de economia + tabela de pricing
│   ├── client.py                 # wrapper opcional da Anthropic SDK
│   ├── languages/
│   │   ├── en.py                 # prompts em ingles
│   │   └── pt.py                 # prompts em portugues
│   └── middleware/
│       └── generic.py            # wrap_call decorator
├── tests/
│   ├── test_validator.py
│   ├── test_render.py
│   └── test_metrics.py
├── benchmarks/
│   ├── tasks.jsonl               # 15 tarefas pareadas
│   ├── run.py                    # benchmark single-shot
│   ├── multi_turn.py             # benchmark agentic
│   ├── fidelity.py               # LLM-as-judge
│   └── compare.py                # relatorio comparativo
├── examples/
│   ├── quickstart.py             # exercita toda a API (offline + online)
│   └── full_flow.py              # comparacao natural vs LIO roundtrip
├── pyproject.toml
├── LICENSE                       # MIT
└── README.md                     # este arquivo
```

---

## Desenvolvimento

```bash
git clone https://github.com/estevaofon/lio-lang
cd lio-lang
uv sync --extra dev              # ou: pip install -e .[dev]

# Rodar os testes
pytest tests/

# Rodar os exemplos (offline, sem API key)
uv run examples/quickstart.py --offline

# Rodar os exemplos com API real (precisa ANTHROPIC_API_KEY em .env)
uv run --extra anthropic examples/quickstart.py
uv run --extra anthropic examples/full_flow.py --prompt "sua pergunta"

# Rodar benchmark completo (custo ~$1.50 em API)
uv run --extra benchmarks python -m benchmarks.run
uv run --extra benchmarks python -m benchmarks.multi_turn
uv run --extra benchmarks python -m benchmarks.fidelity
```

---

## Licenca

Apache License 2.0. Ver `LICENSE` e `NOTICE`.

Copyright 2026 Estevao Fonseca.
