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:

# 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.