Metadata-Version: 2.4
Name: kostria
Version: 0.2.20
Summary: Medição local de uso de IA por projeto, área inferida e conta
Author-email: Pedro Henrique Quadro <184245414+PedroHenrique0713@users.noreply.github.com>
License-Expression: LicenseRef-Kostria-Proprietary
Project-URL: Homepage, https://kostria.hypermind.space
Project-URL: Pricing, https://kostria.hypermind.space/pricing
Project-URL: Privacy, https://kostria.hypermind.space/privacy
Keywords: ai,llm,cost,audit,attribution,claude-code,opencode,codex,token-usage,developer-tools,observability
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# Kostria

<p align="center">
  <img src="https://kostria.hypermind.space/static/brand/og-default.png" alt="Kostria" width="480">
</p>

<p align="center">
  <strong>Pasta não é projeto.</strong> O Kostria segue o arquivo que a IA
  editou de verdade, resolve o repositório certo e infere a área do commit
  e possíveis IDs de ticket — sem proxy, sem SDK, sem mudar código.
</p>

<p align="center">
  <a href="https://pypi.org/project/kostria/"><img src="https://img.shields.io/pypi/v/kostria" alt="PyPI"></a>
  <a href="https://kostria.hypermind.space"><img src="https://img.shields.io/badge/license-free%20to%20use-blue" alt="Gratis para usar"></a>
  <a href="#"><img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="zero dependencies"></a>
  <a href="#"><img src="https://img.shields.io/badge/python-3.11+-blue" alt="Python 3.11+"></a>
</p>

---

## O que e

Ferramentas de IA (Claude Code, OpenCode, Codex CLI, Gemini CLI) custam caro e crescem
rápido. O painel do fornecedor mostra custo por conta — não por projeto, não
por área de trabalho, não pelo ticket validado. Planilha juntada na mão é frágil.

O **Kostria** lê os logs que essas ferramentas já deixam no disco, segue o
arquivo editado até o commit que o fechou e infere dali uma área técnica e
possíveis IDs de ticket. Isso não prova que uma feature foi entregue; conectar
GitHub Issues, Jira ou Linear permite validar os IDs. No Time, cada pessoa
escolhe localmente quais projetos podem entrar no board compartilhado.

```
$ pip install kostria
$ kostria scan

custo total: $2,480.00   tokens: 1.2B   sessões: 89

by commit scope (illustrative):
   checkout-pix (PROJ-118)     $942.40   38%
   onboarding (PROJ-204)       $719.20   29%
   busca (PROJ-091)            $496.00   20%
```

**Por que atribuir por cwd mente:** 65% das edições do Claude Code acontecem
em repos que NÃO são o diretório de trabalho. Worktree, monorepo, sessão de
terminal — o `cwd` joga o custo no projeto errado. O Kostria segue o arquivo.

---

## Quickstart

```bash
pip install kostria
kostria init      # detecta suas pastas de trabalho
kostria scan      # 30 segundos ate o primeiro resultado
kostria serve     # dashboard em http://127.0.0.1:8787
```

Zero dependências. Só Python 3.11+ e stdlib.

---

## O que o Kostria responde

- **Quanto cada projeto consumiu?** Por arquivo editado, não por diretório.
- **Onde se concentrou o uso?** Arquivo → commit → área técnica inferida;
  ticket só é confirmado com o rastreador conectado.
- **Qual modelo é mais eficiente?** Custo por edição entregue, não por token.
- **Quanto da assinatura foi usado?** Separa consumo real do fixo (Claude
  Pro/Max).
- **Tem conta ociosa?** Sinaliza contas sem atividade nos últimos 14 dias.
- **O orçamento vai estourar?** Projeção mensal + previsão de fechamento do mês.
- **O que mudou entre duas janelas?** Compare equivalente de API e tokens por dia corrido, com cobertura de preço, sem confundir referência com fatura.
- **Onde faltou capacidade?** Registre limites, bloqueios e a conta ou o provedor usado para continuar, sem somar quotas incompatíveis.
- **Quando revisar uma assinatura?** Informe a renovação na Carteira e escolha um aviso opcional por e-mail, de 1 a 30 dias antes.

---

## Suporta

| Ferramenta | Coletor | Preço |
|---|---|---|
| Claude Code | `~/.claude*/projects/**/*.jsonl` | Tabela Anthropic publica (medido) |
| OpenCode | `~/.local/share/opencode/opencode.db` | Auto-reportado (confiável) |
| Codex CLI | `~/.codex/sessions/rollout-*.jsonl` | Respostas/deltas + cenário da tabela OpenAI quando modelo e componentes permitem |
| Gemini CLI | `~/.gemini/tmp/*/chats/session-*.jsonl` | Tabela Google publica (medido) |

---

## Planos

| Plano | Preço | Inclui |
|---|---|---|
| **Local** | Grátis | Custo por projeto, conta e modelo (Claude Code), painel local, 1 pessoa e 1 máquina, 30 dias no board |
| **Pro** | R$ 39/mês ou R$ 390/ano | Outros coletores, área inferida do commit/ID de ticket, até 5 máquinas suas, trackers, 1 ano de histórico |
| **Time** | R$ 39 · 29 · 19 por pessoa/mês | Tudo do Pro, board agregado, alerta por e-mail, relatório mensal, máquinas sem limite |
| **Enterprise** | sob consulta | Contrato e necessidades específicas |

No Time você **escolhe os assentos**, com mínimo de 2. Faixas: 2–5 pessoas
R$ 39 por pessoa; 6–20 R$ 29; 21–50 R$ 19. Três assentos custam R$ 117/mês;
dez, R$ 290/mês. O board avisa se medir mais pessoas do que assentos,
sem ajustar a cobrança automaticamente. Veja [os preços vigentes](https://kostria.hypermind.space/pricing).

O motor roda localmente e o código é proprietário. Você pode começar grátis
com Claude Code; Pro e Time liberam os outros coletores e a atribuição fina.
O board hospedado é opcional.
Nos planos Pro e Time, repositórios públicos do GitHub podem validar tickets sem token. Repositórios privados exigem um token de leitura, cifrado pelo Kostria.

---

## Comandos

```bash
kostria scan                          # resumo no terminal
kostria scan --since 30d --compare    # contra mes anterior
kostria scan --budget 3000            # alerta de orcamento
kostria scan --anonymize              # mascara nomes (compartilhavel)

kostria report                        # HTML (abre no navegador)
kostria report --format json -o dados.json
kostria report --format csv  -o custos.csv

kostria serve                         # dashboard local em 127.0.0.1:8787
kostria watch                         # vigia ao vivo no terminal
kostria doctor                        # 11 checagens de integridade
kostria contas --json                 # contas locais e planos individuais precificados
kostria badge -o badge.svg            # selo shields.io local

kostria compartilhar                  # no Time: escolha localmente os projetos que podem subir
kostria compartilhar --conta CONTA    # no Time: inclui uma conta de IA na Carteira do workspace
kostria sync                          # envia somente o recorte autorizado no Time
kostria agendar                       # sync recorrente pelo agendador do SO
kostria agendar --mostrar             # lê o que seria instalado, sem instalar
```

`kostria contas` lista as contas de IA desta máquina, o plano detectado e o
preço público do plano, com fonte e data, e diz quando leu o uso na Anthropic
ou por que não leu. `kostria sync --descobrir-contas`, num terminal, mostra o
que muda e pede confirmação: envia à Carteira as contas detectadas (e-mail
mascarado, plano, estado do login e % de uso) e lê o % de uso de cada conta
Claude em `api.anthropic.com/api/oauth/usage` com o token que o Claude Code já
guarda — só leitura, no máximo a cada 5 minutos, sem renovar nem alterar o
login. Fora de um terminal (cron, script), só envia as contas. O Codex informa
o próprio uso nos logs locais. `kostria contas --revogar` desfaz a
autorização. Quem autorizou numa versão anterior à 0.2.20 continua enviando as
contas, mas a leitura na Anthropic só volta depois de confirmar de novo.

A Carteira faz uma única pergunta por conta: **quem paga**. Plano, estado do
login (ativa, desconectada, parada há N dias), uso da semana e das últimas
5 horas e o aviso de conta usada em várias máquinas vêm da máquina. A data de
renovação não tem fonte local (o reset semanal não é renovação) e fica como
campo opcional. Planos Enterprise aparecem "sob contrato", sem preço público e
sem somar zero. Preço público não é fatura e equivalente de API não mede ROI.

Os preços vêm das tabelas oficiais de Anthropic e OpenAI, lidas por inteiro
todo dia; modelo novo entra no catálogo por dado, sem nova versão da CLI, e o
catálogo chega a cada máquina no sync. Onde a tabela oficial não cobre, o
OpenRouter entra como fonte secundária marcada como tal; variante de nível
(`-pro`, `-high`) de modelo com preço oficial fica sem preço em vez de herdar
o da base. Fonte ilegível conserva a última versão íntegra.

Depois do `kostria login`, os comandos do dia a dia (`scan`, `report`) podem
sincronizar de 6 em 6 horas — sem refazer a varredura. Em workspace Time ou
Enterprise, o primeiro envio fica bloqueado até você rodar
`kostria compartilhar`; projetos não escolhidos não entram no payload, nem como total
anônimo. `kostria compartilhar --limpar` deixa a seleção vazia e remove do
servidor os dados anteriores desta máquina no próximo sync bem-sucedido.
Desligue o envio automático com `--sem-autosync` (ou
`autosync = false` no `kostria.toml`). O `kostria agendar` cobre o caso de
quem passa o dia dentro do agente e nunca digita `kostria`.

---

## Privacidade

- A análise e o relatório rodam localmente e funcionam sem rede. Por padrão,
  `scan` envia um ping anônimo de instalação e consulta o PyPI para avisar de
  atualização; `kostria scan --no-telemetry` desliga os dois nessa execução.
  Dados do trabalho só chegam ao board após `kostria login` e um `sync`
  manual, agendado ou oportunista em `scan`/`report`.
- No workspace pessoal Pro, o `sync` envia o agregado: projeto, dia, custo,
  tokens, área inferida e ID de ticket, os totais por modelo/fornecedor/ferramenta, a base de medição e um
  identificador irreversível por resposta para deduplicação, o nome desta máquina e o
  seu plano de IA (valor pago e equivalente em API) com a conta **mascarada**
  (`a***@dominio`). Nunca caminho de arquivo, nunca conteúdo de sessão, nunca
  o e-mail completo. No Time/Enterprise, só projetos escolhidos localmente
  são enviados; totais globais, assinaturas e inventário de contas ficam fora
  porque poderiam revelar dados pessoais por diferença. Uma conta de IA só
  entra na Carteira do Time se você a incluir com `kostria compartilhar
  --conta`, e só ela é consultada na Anthropic.
- No Time, owner e admin veem o detalhe por dia, projeto e modelo de cada
  pessoa; os demais membros veem o próprio detalhe e o total dos colegas.
- Rodar `kostria login` de novo na mesma máquina substitui o token anterior
  dela (sem somar em dobro), e a troca de seleção alcança o histórico inteiro
  da máquina.
- Não quer mandar o plano? `kostria sync --sem-assinatura`.
- `--anonymize` troca nomes por hash estável para relatórios compartilháveis.
- **Não acredite: confira.** `kostria sync --dry-run -v` imprime o JSON exato
  que subiria — e não envia nada. É a resposta certa para "o que essa
  ferramenta manda do meu trabalho para fora?", e vale a pena rodar antes do
  primeiro `sync`.

```bash
$ kostria sync --dry-run
[dry-run] endpoint: https://kostria.hypermind.space/sync
[dry-run] 255 entries -> workspace 0000…
[dry-run] 3 assinatura(s): a***@empresa.com.br (claude_max_20x, $200.00/mes), …
```

---

## Por que o Kostria é diferente

Não é um proxy (Helicone). Não é tracing de qualidade (Langfuse). Não é FinOps
de cloud (Vantage). É o único que lê os logs que já estão no disco, segue o
arquivo até o commit e infere dali área técnica e ID de ticket — sem SDK, sem proxy, sem
mudar uma linha de código.

---

## Links

- [Site e board do time](https://kostria.hypermind.space)
- [Planos e preços](https://kostria.hypermind.space/pricing)
- [Privacidade](https://kostria.hypermind.space/privacy)
- Suporte e segurança: hypermind.ia@gmail.com

---

## Licença

Proprietária e **gratuita para usar**, inclusive comercialmente dentro da sua
empresa: sem cadastro, sem contagem de assento, sem expiração. O que não se
pode é redistribuir, modificar ou usar o código para construir um concorrente
(texto completo em `LICENSE`).

Até a versão 0.2.3 o pacote saiu sob MIT, e aquele direito não é revogado —
vale para aquelas versões. A licença atual vale da 0.2.4 em diante.

Feito em Vicosa, MG por [Pedro Henrique](https://github.com/PedroHenrique0713).
