kostria 0.1.0__tar.gz

kostria-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,274 @@
+# Arquitetura do kostria
+
+Documento para quem for mexer no código. Baseado no que o código faz de
+fato; se algo aqui divergir da implementação, a implementação manda.
+
+## 1. Visão geral
+
+O `kostria` é um pacote Python de auditoria **local** de custo de IA. Ele lê
+os registros que as ferramentas já gravam na máquina (Claude Code, OpenCode,
+Codex CLI), calcula ou aceita o custo de cada sessão e atribui esse gasto a
+projeto, conta, modelo e — quando há histórico git — a área/feature.
+
+Existe porque o total sozinho não decide nada: o valor do produto está na
+**distribuição** (qual projeto, qual conta, com que evidência). Tudo roda
+offline, sem dependência externa e sem rede (`pyproject.toml` declara
+`dependencies = []`).
+
+## 2. Fluxo de dados
+
+A unidade de troca entre camadas é a `Session` (`collectors/__init__.py`).
+A sessão é o menor recorte em que as ferramentas concordam: Claude Code
+registra por mensagem; OpenCode e Codex agregam por sessão.
+
+```
+  logs locais                 Session[]              dict (relatório)
+  (~/.claude, sqlite,         + meta por             agregado em
+   ~/.codex/...)              coletor                várias dimensões
+       |                         |                        |
+       v                         v                        v
+  +-----------+   +-------------+   +-------------+   +----------+
+  | coletores |-->| atribuição  |-->| report.build|-->| render   |
+  | collect() |   | split_      |   | + analysis  |   | html/md  |
+  |           |   | session_cost|   | + features  |   | csv/json |
+  +-----------+   +-------------+   +-------------+   +----------+
+       ^                                                    ^
+       |                                                    |
+  cache.py (só                                      cli.py (scan,
+  claude_code hoje)                                 report, serve,
+                                                    doctor, ...)
+```
+
+Passos concretos:
+
+1. **Coleta** — `collect_all()` chama cada coletor. Falha de um não derruba
+   os outros; o erro vira entrada em `meta[nome]`.
+2. **Período** (opcional) — `period.filter_sessions` recorta por
+   `started_at` e pela fração de edições dentro da janela (sessão longa
+   que atravessa o mês é rateada e o relatório declara a aproximação).
+3. **Atribuição** — para cada sessão, `split_session_cost` rateia custo e
+   tokens entre projetos e devolve o método usado (`edited` / `read` /
+   `cwd`).
+4. **Agregação** — `report.build` monta um único dict: totais, buckets
+   (`by_project`, `by_tool`, `by_vendor`, `by_account`, `by_model`,
+   `by_provenance`, `by_attribution`), sinais de `analysis.py`,
+   opcionalmente custo por feature via `features_for_repo` e status de
+   orçamento. Comparação entre períodos (`compare.compare_reports`) é
+   anexada depois pela CLI quando `--compare` está ativo.
+5. **Render** — a CLI escolhe o formato. O dict é a fonte única para
+   terminal, HTML (`render.py`), Markdown, CSV, JSON e o dashboard
+   (`serve` + `web/dashboard.html`).
+
+Separar montagem (`report`) de apresentação (`render` / `markdown` / CSV)
+existe de propósito: CLI, dashboard e testes consomem a mesma estrutura.
+
+## 3. Por que a atribuição segue arquivos, não o `cwd`
+
+Documentado no próprio `attribution.py`:
+
+> O diretório da sessão mente. O agente edita vários repositórios a partir
+> de um cwd só (working dirs adicionais, worktrees, pastas temporárias).
+> Medir por cwd joga o custo no projeto errado. A atribuição segue os
+> ARQUIVOS efetivamente editados.
+
+Cascata de evidência em `split_session_cost`, do mais forte ao mais fraco
+(`ATTRIBUTION`):
+
+| método   | evidência                                      |
+|----------|------------------------------------------------|
+| `edited` | paths em `session.edits` (escrita = entrega)   |
+| `read`   | paths em `session.reads` (leitura = contexto)  |
+| `cwd`    | diretório declarado, sem arquivo tocado        |
+
+O rateio é uniforme entre os projetos encontrados nos paths (custo/N,
+tokens//N). O Claude Code popula `edits` e `reads` a partir das tool calls
+(`Edit`/`Write`/… e `Read`/`Grep`/`Glob`/…). O comentário no coletor é
+explícito: sem leituras, toda sessão de investigação cairia no diretório
+declarado — que mente.
+
+`ProjectResolver` resolve path → nome de projeto com, nesta ordem:
+índice de worktrees (`git worktree list` + convenção `<repo>-wt`),
+projeto codificado em scratch de sessão (`-home-user-code-app`),
+`git rev-parse --git-common-dir`, primeiro nível do workspace, ou basename.
+Worktree não é outro projeto; scratch/tmp/UUID viram rótulos genéricos.
+
+Dentro de um repo, a unidade fina de feature é o **commit** (não o PR):
+`features_for_repo` liga cada edição ao primeiro commit posterior que tocou
+o arquivo e agrega por escopo convencional (`feat(escopo): …`) e por ticket
+no subject/body.
+
+## 4. Proveniência: nenhum número sem classificação
+
+Regra em `pricing.py`:
+
+> Nenhum número sai daqui sem `provenance`. Preço que não pode ser
+> verificado devolve custo `None`, nunca uma estimativa silenciosa.
+
+Camadas em `PROVENANCE`:
+
+| valor             | significado                                              |
+|-------------------|----------------------------------------------------------|
+| `measured`        | tokens do log + tabela de preço pública                  |
+| `self_reported`   | custo calculado pela própria ferramenta                  |
+| `tokens_only`     | tokens medidos, sem tabela de preço verificada           |
+| `assumed`         | preço de um modelo **assumido pelo operador**, não no log|
+| `uninstrumented`  | a ferramenta não registra consumo (legenda; uso futuro)  |
+
+Como cada coletor preenche isso hoje:
+
+- **Claude Code** — cada sessão com tokens sai com `provenance="measured"`.
+  Por evento, `anthropic_usage_cost` precifica se o modelo está na tabela;
+  modelo desconhecido incrementa `meta["unpriced"]` e não soma USD (os
+  tokens do evento ainda entram no total da sessão).
+- **OpenCode** — lê o custo do SQLite → `self_reported` (vários
+  fornecedores; não reaplicamos tabela própria).
+- **Codex** — `openai_usage_cost`. Sem breakdown input/output, ou modelo
+  desconhecido → `Cost(None, tokens, "tokens_only")`. Com
+  `--assume-codex-model`, se precificar, a sessão vira `assumed`.
+
+No relatório, `priced_cost` soma só `measured` + `self_reported`. A
+**cobertura** é sobre tokens (`priced_tokens / total_tokens`), não sobre
+custo: custo não apurado entra como 0 e faria cobertura por USD parecer
+sempre 100%. O doctor ainda exige que `tokens_only` tenha custo ~0.
+
+## 5. Cache incremental (`cache.py`)
+
+Varrer o histórico inteiro a cada execução é desperdício: sessão
+encerrada não muda. O cache guarda o resultado por **arquivo de origem**,
+com chave `mtime_ns:size`. Fica em `~/.cache/kostria/` (ou `$XDG_CACHE_HOME`).
+Apagar a pasta é sempre seguro. `VERSION` no módulo invalida o formato
+inteiro quando o cálculo muda. Gravação é atômica (`.tmp` + `os.replace`).
+
+Hoje só o coletor do Claude Code usa `SessionCache` (é quem varre a árvore
+  de `*.jsonl` sob cada config dir). Dedupe por id de mensagem continua
+  valendo mesmo em hit de cache (retomada/compactação copia mensagens
+  entre arquivos).
+
+### A armadilha mutation-on-read
+
+`_from_dict` precisa extrair `edits`/`reads` do dict serializado. A versão
+bugada fazia `d.pop("edits")` **no dicionário ainda referenciado por
+`self._data`**. Consequência, documentada no próprio código:
+
+> Ler o cache destruía o cache, e a atribuição por arquivo morria em
+> silêncio a partir da terceira execução (o custo total continuava certo).
+
+A correção é copiar antes de mutar: `d = dict(d)` e só então `pop`.
+
+### Por que há teste de regressão específico
+
+`tests/test_cache.py`, classe `TestCacheSurvivesReadWriteCycles`:
+
+- `test_edits_survive_three_cycles` — put → save → get/save × 3; as
+  edições têm que continuar lá.
+- `test_read_does_not_mutate_internal_state` — após `get`, a chave
+  `"edits"` ainda existe em `c._data[...]["sessions"][0]`.
+
+O bug era invisível para qualquer asserção de total: o USD batia, a
+distribuição por projeto não. Por isso o teste ataca o estado interno e o
+ciclo de regravação, não só o round-trip feliz.
+
+## 6. `doctor.py`
+
+Nasceu de um incidente real (descrito no docstring do módulo): um bug de
+cache apagou as edições de todas as sessões e derrubou a atribuição por
+arquivo, enquanto o **custo total continuou correto**. Conferir o total
+não prova distribuição.
+
+A verificação compara **rotas independentes** e invariantes, por exemplo:
+
+- coleta sem cache × com cache (total e `by_project`);
+- contagem de edições preservada;
+- soma de `by_project` / `by_account` / `by_attribution` fecha com o total;
+- toda chave de proveniência tem legenda; `tokens_only` não inventa USD;
+- o relatório serializa como JSON estrito (`allow_nan=False`);
+- modo anônimo não vaza e-mail nem `/home/...`;
+- avisos (não críticos): fração com evidência de arquivo, cobertura de
+  preço, custo só-cwd, dedupe ativa.
+
+### Disco em movimento
+
+`_log_fingerprint` captura `(mtime, size)` de todo jsonl do Claude Code
+antes e depois das coletas. Se os logs mudaram durante o doctor — típico
+quando a sessão que roda o doctor está gravando no próprio projeto
+auditado — divergência entre fresco e cache é **inconclusive**, não
+corrupção. Nesses casos o check é marcado `skipped` em vez de falha, para
+não gritar lobo.
+
+## 7. Convenções do projeto
+
+- **Sem dependência de terceiros** — só stdlib. Python `>=3.10`
+  (`tomllib` para config exige 3.11+; abaixo disso a config é ignorada com
+  aviso).
+- **Sem rede na apuração** — lê disco local. `serve` escuta só em
+  `127.0.0.1` de propósito (relatório tem dado sensível).
+- **Config** — `./.kostria.toml` ou `~/.config/kostria/config.toml`; projeto
+  sobrepõe usuário; CLI tem a última palavra (`config.apply` só preenche
+  buracos).
+- **Testes** — `tests/`, `unittest`.
+- **Rodar a suite:**
+
+  ```bash
+  python3 -m unittest discover -s tests
+  ```
+
+- **Tom do código** — comentários explicam *por que*, não o óbvio; falha
+  de dado de terceiro não pode derrubar a apuração inteira (`_int`
+  tolerante, coletor que devolve `available: False`, etc.).
+- **JSON estrito** — nunca emitir `NaN`/`Infinity` (já quebrou o dashboard
+  em silêncio; ver `compare._delta` e `cli._json_dump`).
+
+## 8. Como adicionar um coletor
+
+Referência: `collectors/__init__.py` e os três coletores existentes.
+
+1. Crie `kostria/collectors/<ferramenta>.py` com:
+
+   ```python
+   def collect(... ) -> tuple[list[Session], dict]:
+       ...
+   ```
+
+   - Devolve `(lista_de_Session, meta)`.
+   - Se a ferramenta não estiver instalada / sem dados: `([], {"available": False})`
+     (ou equivalente), sem levantar.
+   - Exceção não tratada ainda é engolida por `collect_all` e vira
+     `meta[nome] = {"error": ...}`, mas o ideal é falhar de forma controlada.
+
+2. Preencha `Session` com o que for confiável:
+
+   - `tool`, `account`, `vendor`, `tokens`, `provenance` (obrigatório no
+     sentido de contrato — ver `PROVENANCE`);
+   - `cost` como `float` ou `None` (nunca chute silencioso);
+   - `edits` / `reads` como `list[Edit]` se a ferramenta expuser paths —
+     isso alimenta atribuição forte; se não expuser, deixe vazio e a
+     sessão cairá em `cwd` (como OpenCode/Codex hoje);
+   - `models`, `token_mix`, `started_at`, `source`, `cwd` conforme existir.
+
+3. Registre em `collect_all`:
+
+   ```python
+   from . import claude_code, codex, opencode, minha_ferramenta
+   ...
+   for name, mod in (..., ("minha_ferramenta", minha_ferramenta)):
+   ```
+
+   Passe kwargs específicos só quando o coletor os aceitar (padrão atual:
+   `use_cache` só no Claude Code, `assume_model` só no Codex).
+
+4. Precificação:
+
+   - Se houver tabela pública estável, coloque em `pricing.py` e devolva
+     `Cost` com `measured` ou `tokens_only`.
+   - Se a ferramenta já calcula o custo, use `self_reported` e documente
+     no docstring do coletor (caso OpenCode).
+   - Se o operador puder forçar premissa, use `assumed` e exponha flag na
+     CLI/config (caso Codex).
+
+5. Testes em `tests/` com fixtures mínimas (arquivo/sqlite temporário),
+   cobrindo: ausência da ferramenta, parse tolerante, proveniência
+   correta, e — se houver cache — ciclo get/save sem mutar estado.
+
+Não é necessário implementar cache no coletor novo; só vale a pena se a
+varredura for cara e o artefato for imutável por `mtime`/tamanho como no
+Claude Code.

kostria-0.1.0/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+Tudo o que mudou no Kostria, agrupado por sessão de trabalho e na ordem em que foi construído.
+
+## [2026-07-25]
+
+### Núcleo do produto
+
+- Coletores multi-conta para Claude Code, OpenCode (SQLite) e Codex.
+- Custo por feature: arquivo → commit → área/item do board.
+- Atribuição pelos arquivos editados, não pelo diretório de trabalho atual.
+- Worktree resolvido para o repositório principal via `git-common-dir`.
+- Sinais iniciais: reprocessamento, retrabalho, eficiência por modelo e projeção.
+- CLI `scan`, `report` e `serve` com relatório HTML.
+- Exportação CSV para o financeiro (152 linhas por dimensão).
+- README, landing e testes iniciais; `pyproject` com descoberta explícita de pacotes para evitar falha no `pip install -e`.
+- Recuperação do projeto de origem a partir do scratch de sessão do Claude Code, decodificando o caminho codificado em `/tmp/claude-<uid>/<cwd-codificado>/<sessão>/` e casando contra os projetos existentes.
+- `--repo` repetível e descoberta automática de repositórios git entre os projetos que mais gastaram.
+- Arquivo de configuração `.kostria.toml` para guardar padrões de workspace, repo, budget, período e modelo assumido; chave desconhecida ou tipo errado viram aviso no stderr, e TOML quebrado não derruba o comando.
+- `--format md` para resumo colável em e-mail ou ticket.
+- `kostria init` detecta pastas de trabalho plausíveis e já escreve o `.kostria.toml` inicial.
+- CSV mais completo incluindo as dimensões `by_attribution` e `project_budgets`.
+- Atribuição em cascata de evidência: escreveu > leu > diretório. Read, NotebookRead, Grep e Glob passam a trazer o caminho como evidência secundária.
+- Sinais novos: dias fora do padrão, sessões mais caras e perfil semanal.
+- `kostria watch` para vigia ao vivo no terminal.
+- Selo SVG local (`kostria badge`) sem depender de serviço externo.
+
+### Recorte temporal e comparação
+
+- `--since`/`--until` aceitam AAAA-MM-DD, `30d`, `2w`, `6m`, `1y`, `hoje` e `ontem`.
+- Sessão que atravessa a fronteira do período entra rateada pela fração de edições dentro da janela, sem mutar a sessão original.
+- `--budget` compara a projeção mensal com o limite e alerta se estoura.
+- `--compare` mede a janela imediatamente anterior, de mesma duração, e mostra as maiores variações por projeto, conta, modelo e fornecedor.
+- Corrigido: a duração da janela passou a contar os dois extremos (por exemplo, 08 a 14 vira 7 dias, não 6).
+
+### Integridade e cache
+
+- Cache incremental da coleta: validação por mtime e tamanho, passando de 3,6s para 0,6s; `--no-cache` para ignorar.
+- **Corrigido**: "ler o cache destruía o cache". `_from_dict` fazia `d.pop('edits')` sobre o dicionário guardado em `self._data`, então a leitura apagava a chave e o `save()` seguinte regravava o cache sem as edições. A partir do terceiro ciclo sobravam 17 edições de 1264 e toda a atribuição por arquivo colapsava no cwd. A correção copia o dict antes do `pop`; caches corrompidos são invalidados pela `VERSION` 4.
+- `kostria doctor` para verificação de integridade dos números, comparando rotas independentes (cache × leitura direta, soma das partes, proveniência, custo negativo, custo não atribuído, deduplicação etc.).
+- Tabela de preços da OpenAI completa a lacuna do Codex ($413,20): input, cached input e output separados; `--assume-codex-model` permite declarar o modelo ausente com proveniência `assumed`.
+- Tratamento de dados malformados: JSONL corrompido, arquivo binário, token não numérico, valor negativo, timestamp inválido, período invertido, caminho com acento/quebra de linha/aspas e SQLite corrompido. Um único valor estranho deixava de derrubar a coleta inteira.
+- **Corrigido**: `float('inf')` na variação percentual era serializado como `Infinity`, que não é JSON válido, e o dashboard ficava vazio sem logar erro no servidor. Sem base anterior, `pct` passou a ser `None` e o consumidor usa o campo `new`.
+- **Corrigido**: modo anônimo vazava e-mail real e caminho absoluto da casa em `collectors.config_dirs` e em `signals`. A limpeza agora é recursiva e cega ao formato, varrendo o payload por padrões de e-mail e caminho absoluto.
+- **Corrigido**: `kostria doctor` falhava intermitentemente quando o próprio Claude Code gravava logs durante a leitura. Agora ele tira uma "fotografia" (mtime + tamanho) dos logs antes do ciclo e marca as checagens vulneráveis como "pulado" quando o disco está em movimento.
+- Serialização JSON com `allow_nan=False` para falhar alto em vez de emitir payload inválido.
+- Servidor passou a atender em paralelo (`ThreadingHTTPServer`) e a reaproveitar a apuração com lock; falhas do processo viram HTTP 500 em vez de derrubar o servidor.
+
+### UX e UI do painel
+
+- Dashboard interativo local servido por `kostria serve`.
+- Dashboard reescrito com direção visual própria: régua proporcional de atribuição no topo, tipografia monoespaçada para números, paleta fria (teal para valor medido, âmbar para lacuna declarada), navegação lateral com deep-link por hash e acessibilidade.
+- Relatório estático com a mesma identidade visual do dashboard; regras de impressão para não cortar blocos no PDF.
+- Landing com a tese como demonstração; depois com seção de objeções e comparação honesta.
+- Dashboard com busca global, atalhos de teclado, cópia de valor em dólar com um clique, exportação client-side (JSON/CSV), skeleton de carregamento, estados vazios específicos, tooltips de ajuda, microcopy revisado e indicador de atualidade relativa.
+- **Corrigido**: h1 da landing quebrava em 4 linhas em tela larga; ajustado para 3 linhas.
+- **Corrigido**: vazamento horizontal no painel em tela estreita (item flex não encolhia e a página ganhava largura extra).
+- **Corrigido**: cinza de apoio estava abaixo do mínimo de contraste WCAG AA; trocado por `#5a6c7a`.
+- **Corrigido**: entidades HTML escapavam como literais na tela (`Sess&otilde;es`); texto acentuado vai direto em UTF-8.
+- Corrigido: mockups de terminal perdiam quebra de linha por falta de `white-space: pre-wrap`.
+
+### Orçamento por projeto e previsão de fim de mês
+
+- `--project-budget NOME=VALOR` (repetível) e tabela `[project_budgets]` no `.kostria.toml` para alertar quando um projeto específico estoura, não só o total da organização.
+- `end_of_month_forecast()` responde quanto já foi gasto desde o dia 1 do mês corrente mais a média recente extrapolada pelos dias que faltam no calendário (não numa janela móvel genérica).
+- Exposto em `scan`, no relatório HTML, em `--format md` e no dashboard.
+
+### Testes e qualidade
+
+- **Bug de teste revelado por mutação**: os testes de preço anteriores importavam constantes do módulo e calculavam `expected = 3.0 * CACHE_READ`, o que fazia a expectativa mudar junto com o bug. Foram travados em literais calculados à mão, e as 5 mutações passaram a falhar.
+- Testes adversariais para dados corrompidos e bordas de calendário (dia 1, último dia do mês, fevereiro bissexto e não-bissexto).
+- Testes de contraste travando onze pares cor/fundo com cálculo de razão, não com impressão visual.
+- Teste de ponta a ponta que roda a CLI de verdade sobre um `HOME` sintético, em vez de substituir o coletor por um duplo.
+- Total final: 287 testes.
+
+### Outras correções
+
+- Corrigido: `--anonymize` antes do subcomando era ignorado silenciosamente por causa do `argparse` com `parents=`; as flags comuns passaram a ser lidas do `argv` inteiro e reaplicadas.
+- Corrigido: `main()` devolvia o relatório como código de saída depois que `doctor` foi ligado; apenas `doctor` devolve código de erro.
+- Corrigido: `json.load(open(cand))` sem fechar o arquivo em `_account_of`, achado pelo `ResourceWarning` nos testes.

kostria-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pedro Henrique Quadro
+
+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.

kostria-0.1.0/MANIFEST.in

@@ -0,0 +1,16 @@
+# Inclui os assets web embarcados no pacote (dashboard, landing e vendor
+# vendorizado) tanto na sdist quanto na wheel. Sao necessarios para que
+# `kostria serve` funcione quando instalado via pip.
+recursive-include kostria/web *.html
+recursive-include kostria/web/vendor *.js
+recursive-include kostria/web/vendor/fonts *
+recursive-include kostria/landing *.html
+recursive-include kostria/landing/vendor *.js
+recursive-include kostria/landing/vendor *.mjs
+recursive-include kostria/landing/vendor/fonts *
+
+# Metadados e docs da raiz.
+include README.md
+include CHANGELOG.md
+include ARCHITECTURE.md
+include LICENSE

kostria-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: kostria
+Version: 0.1.0
+Summary: Auditoria local de custo de IA: atribui gasto a projeto, feature e conta
+Author-email: Pedro Henrique Quadro <184245414+PedroHenrique0713@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/PedroHenrique0713/kostria
+Project-URL: Repository, https://github.com/PedroHenrique0713/kostria
+Project-URL: Issues, https://github.com/PedroHenrique0713/kostria/issues
+Project-URL: Changelog, https://github.com/PedroHenrique0713/kostria/blob/main/CHANGELOG.md
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+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 nao e projeto.</strong> O Kostria segue o arquivo que a IA
+  editou de verdade, resolve o repositorio certo e extrai dali feature e
+  ticket do Jira — em 30 segundos, sem proxy, sem SDK, sem mudar codigo.
+</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="LICENSE"><img src="https://img.shields.io/pypi/l/kostria" alt="MIT"></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.10+-blue" alt="Python 3.10+"></a>
+</p>
+
+---
+
+## O que e
+
+Ferramentas de IA (Claude Code, OpenCode, Codex CLI) custam caro e crescem
+rapido. O painel do fornecedor mostra custo por conta — nao por projeto, nao
+por feature, nao por ticket. Planilha juntada na mao e lenda com erro.
+
+O **Kostria** le os logs que essas ferramentas ja deixam no disco, segue o
+arquivo editado ate o commit que o fechou, e extrai dali o escopo da feature e
+o ticket. O board do time agrega isso pra todo mundo, sem a sessao bruta sair
+do disco de ninguem.
+
+```
+$ pip install kostria
+$ kostria scan
+
+custo total: $2,480.00   tokens: 1.2B   sessoes: 89
+
+by feature:
+   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 edicoes do Claude Code acontecem
+em repos que NAO sao o diretorio de trabalho. Worktree, monorepo, sessao 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 dependencias. So Python 3.10+ e stdlib.
+
+---
+
+## O que o Kostria responde
+
+- **Quanto cada projeto consumiu?** Por arquivo editado, nao por diretorio.
+- **Quanto cada feature custou?** Arquivo → commit → escopo + ticket.
+- **Qual modelo e mais eficiente?** Custo por edicao entregue, nao por token.
+- **Quanto da assinatura foi usado?** Separa consumo real do fixo (Claude
+  Pro/Max).
+- **Tem conta ociosa?** Sinaliza contas sem atividade nos ultimos 14 dias.
+- **O orcamento vai estourar?** Projecao mensal + previsao de fechamento do mes.
+
+---
+
+## Suporta
+
+| Ferramenta | Coletor | Preco |
+|---|---|---|
+| Claude Code | `~/.claude*/projects/**/*.jsonl` | Tabela Anthropic publica (medido) |
+| OpenCode | `~/.local/share/opencode/opencode.db` | Auto-reportado (confiavel) |
+| Codex CLI | `~/.codex/sessions/rollout-*.jsonl` | Tokens (sem tabela OpenAI) |
+
+---
+
+## Planos
+
+| Plano | Preco | Inclui |
+|---|---|---|
+| **Local** | Gratis | Motor de atribuicao completo, painel local, retencao 90d |
+| **Pro** | $9/mes | Integracao Jira/Linear/GitHub Issues, sync cross-machine |
+| **Team** | $14/assento/mes | Board agregado do time, budget alerts, org-scoped sync |
+
+O motor e open source (MIT). O board do time e opcional e hospedado.
+
+---
+
+## 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 badge -o badge.svg            # selo shields.io local
+
+kostria sync                          # envia agregado pro board do time
+```
+
+---
+
+## Privacidade
+
+- Roda 100% local. Nada sai da maquina sem voce pedir.
+- O `kostria sync` envia so o agregado: projeto, dia, custo, tokens. Nunca
+  caminho de arquivo, nunca conteudo de sessao, nunca e-mail.
+- `--anonymize` troca nomes por hash estavel para relatorios compartilhaveis.
+
+---
+
+## Por que o Kostria e diferente
+
+Nao e um proxy (Helicone). Nao e tracing de qualidade (Langfuse). Nao e FinOps
+de cloud (Vantage). E o unico que le os logs que ja estao no disco, segue o
+arquivo ate o commit e extrai dali feature e ticket — sem SDK, sem proxy, sem
+mudar uma linha de codigo.
+
+[Mapa completo de concorrentes →](COMPETITORS.md)
+
+---
+
+## Docs
+
+- [Estrategia de lancamento](GTM.md)
+- [Mapa de concorrentes](COMPETITORS.md)
+- [One-pager / pitch](PITCH.md)
+- [Arquitetura](ARCHITECTURE.md)
+- [Guia de contribuicao](CONTRIBUTING.md)
+- [Saas blueprint](SAAS-BLUEPRINT.md)
+- [Checklist de lancamento](LAUNCH.md)
+
+---
+
+## Testes
+
+```bash
+python3 -m unittest discover -s tests   # CLI: 388 testes
+cd saas && python3 -m pytest -q         # SaaS: 123 testes
+```
+
+O SaaS nao exige Postgres: a suite injeta um pool em memoria.
+
+---
+
+## Licenca
+
+MIT. O CLI e livre. O board hospedado e opcional.
+
+Feito em Vicosa, MG por [Pedro Henrique](https://github.com/PedroHenrique0713).