Metadata-Version: 2.4
Name: kob
Version: 0.0.1
Summary: SDK Python para abstrair a configuração de agentes de IA em uma única classe
Project-URL: Homepage, https://github.com/ygorPaulo074/kob
Project-URL: Repository, https://github.com/ygorPaulo074/kob
Author: Paulo Ygor Oliveira Araújo
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Requires-Dist: tomli>=2.0; python_version < '3.11'
Description-Content-Type: text/markdown

# kob

SDK Python open source para abstrair a configuração de **agentes de IA** em uma única classe. O objetivo é que o desenvolvedor só precise instanciar a classe do agente e chamar métodos de uma linha — toda a complexidade de conexão, autenticação e configuração fica encapsulada na SDK.

> Status: em design, ainda não implementado.

## Client: sync e async

A SDK oferece duas classes com a mesma superfície de métodos:

- `Agent` — client síncrono, pra scripts simples, notebooks, CLIs.
- `AsyncAgent` — client assíncrono, pra apps que já rodam em event loop (ex: servidores web).

O dev escolhe qual importar conforme o contexto do projeto dele.

## Configuração

A configuração é externa, via arquivo dedicado `agent.toml` (não usa `pyproject.toml`). TOML foi escolhido sobre YAML (armadilhas de parsing, dependência externa) e JSON (sem comentários, verboso pra edição manual) — parser via stdlib `tomllib` (Python 3.11+) ou `tomli` (3.9/3.10).

Segredos (como API keys) nunca ficam direto no TOML. O arquivo referencia o **nome** da variável de ambiente, e a SDK lê o valor real na instanciação:

```toml
# agent.toml
model = "..."
api_key_env = "KOB_API_KEY"
```

### Cadeia de resolução, por campo de config

Cada valor de configuração é resolvido nesta ordem de prioridade:

1. **Argumento explícito** no construtor (`Agent(model="...")`) — maior prioridade.
2. **`agent.toml`**.
3. **Variável de ambiente**.
4. Se nenhuma das três fontes tiver o valor → erro explícito.

Cada valor resolvido é logado via `logging` (não `print`, pra não contaminar o stdout do consumidor da SDK), indicando de qual fonte veio: argumento explícito, `agent.toml` ou env var.

Erros de descoberta de config são específicos por etapa: arquivo não encontrado, TOML malformado, ou env var referenciada no TOML mas ausente no ambiente.

## Publicação e desenvolvimento

- **Distribuição:** PyPI.
- **Versionamento:** tags no GitHub, releases automatizadas via GitHub Actions.
- **Testes:** aplicados durante o desenvolvimento; após a publicação, abre para a comunidade reportar bugs via fóruns.
- **Documentação:** este README + GitHub Pages.
- **Roadmap de linguagem:** Python primeiro; outras linguagens depois — isso motivou preferir formatos/convenções de config portáveis (arquivo TOML dedicado) em vez de amarrar a algo específico do ecossistema Python.

## Em aberto

- Regra de parada da busca de diretório do `agent.toml` (subir até a raiz do filesystem vs. parar em um marcador tipo `.git`).
- Superfície pública final — métodos concretos do agente.
- Confirmação de disponibilidade do nome `kob` no PyPI.
