jasveerai88/gst-hst-tracker

gst-hst-tracker — skill de agente

Propósito

Freelancers canadenses e proprietários individuais rastreiam GST/HST em planilhas e descobrem o limite de pequeno fornecedor de $30.000 da CRA depois de ultrapassá-lo. Esta ferramenta lê um livro-caixa de transações datadas e produz (a) por trimestre: GST/HST coletado, ITCs e imposto líquido devido com uma seção de preparação de renda/despesas estilo T2125, (b) o teste de limite: receita tributável dos últimos 4 trimestres civis contra o limite de $30.000, com margem ou alarme de ultrapassagem, e (c) uma visão por província do mesmo livro-caixa: sistema tributário, coletado, ITCs e líquido por província, com o componente provincial mostrado apenas na medida em que os dados suportam (QST registrado como valores memo mais uma estimativa em vendas de QC não registradas; PST/RST como estimativas de exposição taxa×vendas). Biblioteca padrão Python pura; apenas local; lê um arquivo de livro-caixa, não grava nada.

O núcleo honesto desta ferramenta: é um auxílio de rastreamento e cálculo, não aconselhamento fiscal e não um arquivamento da CRA. Cada relatório carrega essa isenção de responsabilidade, e qualquer coisa que você escrever a partir de sua saída também deve carregá-la. Nunca calcula penalidades ou juros.

Quando usar / não usar

Use quando:

• Preparar os valores de GST/HST de um trimestre a partir de um livro-caixa de transações: coletado, ITCs, devido líquido.
• Verificar o quão próximo um freelancer está do limite de $30.000 de registro, ou se o ultrapassou.
• Organizar categorias de renda e despesas em uma visão de preparação estilo T2125 para a temporada de declaração.
• Um agente precisa de números GST/HST canadenses em JSON nos quais possa confiar.

NÃO use quando:

• O usuário precisa de aconselhamento fiscal, um arquivamento ou uma decisão sobre suas obrigações — esta ferramenta não pode fornecer isso. Encaminhe-o para a CRA ou um contador qualificado.
• A pergunta envolve penalidades ou juros — nunca computados.
• Os livros são livros QST de Quebec: QST é apenas memo aqui (veja Limitações). PST de BC / PST de SK / RST de MB aparecem apenas como estimativas de exposição na visão provinces — nunca como impostos devidos ou créditos.
• O livro-caixa está desatualizado: a janela de limite está ancorada na transação mais recente, então um livro-caixa desatualizado fornece uma janela desatualizada. Diga isso se as datas parecerem antigas.

Instalação

pipx install git+https://github.com/jasveerai88/gst-hst-tracker
# ou: pip install git+https://github.com/jasveerai88/gst-hst-tracker

(Não está no PyPI — a forma git+ é a instalação.) A partir de um checkout fonte, python3 src/gst_hst_tracker.py ... é equivalente.

Comandos

# Relatório trimestral (entrada JSON ou CSV; saída 0 em caso de sucesso)
gst-hst-tracker report LEDGER.json
gst-hst-tracker report LEDGER.csv --json

# Apenas um trimestre civil ou um ano
gst-hst-tracker report LEDGER.json --period 2026-Q1
gst-hst-tracker report LEDGER.json --period 2026

# Alarme de pequeno fornecedor (saída 1 quando ultrapassado, 0 caso contrário)
gst-hst-tracker threshold LEDGER.json [--limit 30000]

# Visão por província (saída 0 em caso de sucesso)
gst-hst-tracker provinces LEDGER.json
gst-hst-tracker provinces LEDGER.json --period 2026-Q1 --json

# Também exibir equivalentes em INR (taxa por 1 CAD)
gst-hst-tracker report LEDGER.json --cad-to-inr 67.97

# Substituir uma taxa de província quando ela mudar
gst-hst-tracker report LEDGER.json --rate NS=15

Linhas de entrada (lista JSON, objeto {"transactions": [...]} ou CSV com os mesmos cabeçalhos): date (YYYY-MM-DD, obrigatório), kind (income|expense, obrigatório), description (obrigatório), amount (CAD pré-imposto, obrigatório, ≥ 0), province (código de duas letras, obrigatório); opcional tax (GST/HST cobrado/pago — omita para calcular a partir da taxa da província; 0 significa taxa zero e é respeitado), qst (apenas linhas do QC; rastreado separadamente, nunca no líquido), category (apenas despesas; agrupamento estilo T2125).

O modelo (declare-o ao relatar resultados)

• Imposto líquido devido por trimestre civil = GST/HST coletado sobre renda − ITCs (GST/HST pago em despesas). Líquido negativo = ITCs excedem coletas: uma posição de reembolso, não dinheiro em mãos.
• Limite: suprimentos tributáveis (apenas linhas de renda) nos últimos 4 trimestres civis terminando no trimestre da transação mais recente. O teste da CRA é excede $30.000 — exatamente $30.000 ainda é pequeno fornecedor (status: "at", saída 0).
• Padrões de taxa em novembro de 2026: GST 5% (AB BC MB NT NU SK YT), HST 13% ON, HST 15% NB/NL/PE, HST 14% NS (reduzida de 15% em 01/04/2025), QC = GST 5% parte federal apenas.
• QST (9,975%) é um imposto separado da Revenu Québec: valores qst fornecidos aparecem apenas como totais memo e nunca entram no líquido.
• Visão por província (provinces): a mesma matemática federal agrupada pela província da linha. Impostos provinciais codificados, carimbados "Taxas codificadas, verificadas em 2026-11 — verifique junto às fontes CRA/provinciais antes de arquivar": QST 9,975% (QC), PST 7% (BC), PST 6% (SK), RST 7% (MB); províncias HST não têm componente provincial separado. QC mostra totais QST registrados mais uma estimativa em linhas de renda QC sem qst registrado; BC/SK/MB mostram apenas uma estimativa de exposição taxa×vendas, e nenhum ITC provincial (PST/RST sobre insumos é geralmente um custo). Arredondamento: os valores por província são arredondados para centavos e o resumo soma esses valores arredondados, então sempre reconcilia com os blocos de província.

Esquema JSON de saída (--json)

report: tool ("gst-hst-tracker"), version, command ("report"), file, currency ("CAD"), rates (por província rate_pct + rótulo, carimbado as_of: "2026-11", mais a nota QST), cad_to_inr (taxa ou null), period_filter (string ou null), periods, totals, disclaimer.

Cada período: period (ex.: "2026-Q1"), quarter ([2026, 1]), income_total, expense_total, gst_hst_collected, itcs, net_tax_owing, qst_collected, qst_paid, transactions, t2125 (gross_business_income, expenses_by_category, total_expenses). totals soma os mesmos campos entre os períodos exibidos. Com --cad-to-inr, campos monetários ganham irmãos *_inr.

threshold: os campos comuns mais latest_transaction, window_end_quarter, quarters (quatro entradas {quarter, income}, mais antigo primeiro), rolling_total, limit, headroom (0 quando ultrapassado), over_by (0 quando não ultrapassado), crossed (bool), status ("under" | "at" | "crossed"), rule, disclaimer.

provinces: os campos comuns mais provincial_rates (stamp, qst_rate_pct, taxes — por província federal rótulo e provincial_tax {name, rate_pct} ou null), rounding_rule, provinces, totals, disclaimer. Cada entrada em provinces: province, tax_system (construído a partir das taxas efetivas, ex.: "GST 5% + PST 7%"), income_total, expense_total, gst_hst_collected, itcs, net_tax_owing, transactions, e provincial — null para províncias apenas GST e HST; caso contrário {name, rate_pct, recorded_collected, recorded_paid, recorded_net} (números para QC, null para BC/SK/MB — nada é registrado para elas), estimate_base, estimated_on_sales, note. totals adiciona qst_recorded_collected / qst_recorded_paid / qst_recorded_net e provincial_estimated_on_sales.

Em caso de erro, stdout é um único objeto: {"error": "<mensagem>"} (erros de validação nomeiam a linha: "linha 2: ...") com código de saída 2 — incluindo erros de uso do argparse no modo --json. Nunca texto simples, nunca um traceback.

Códigos de saída

• report: 0 — relatório computado. 2 — erro.
• provinces: 0 — visão computada. 2 — erro. (Sem estado de saída 1: a visão é informativa; o alarme está em threshold.)
• threshold: 0 — total acumulado está abaixo ou exatamente no limite: ainda é um pequeno fornecedor com base nesses números. 1 — LIMITE ULTRAPASSADO: o total acumulado excede o limite e o registro de GST/HST é obrigatório. Esta é uma constatação, não uma falha: destaque-a proeminentemente. 2 — erro: nenhum número foi produzido; não cite nenhum.
• Erros em qualquer comando saem com 2 e uma mensagem limpa (ou o objeto {"error": ...} no modo --json).

Limitações e regras de honestidade que o agente deve respeitar

• Não é aconselhamento fiscal, não é um arquivamento. Nunca apresente a saída desta ferramenta como aconselhamento ou como uma declaração arquivada. A isenção de responsabilidade em cada saída é essencial: mantenha-a anexada a qualquer resumo que você escrever.
• As taxas são padrões de novembro de 2026, não fatos atuais. Cite-as como "os padrões de novembro de 2026 da ferramenta" e observe que são substituíveis. Nova Escócia está a 14% (era 15% até 31/03/2025) — se os números de um usuário foram computados a 15% para NS, vale a pena sinalizar, não aceitar silenciosamente.
• Exatamente $30.000 NÃO é ultrapassado. O teste da CRA é "excede $30.000". Se status for "at", relate "ainda um pequeno fornecedor, margem zero" — nunca "deve se registrar".
• Saída 1 do threshold é a ferramenta funcionando. Significa que o alarme disparou. Relate o total acumulado, o valor excedente e que o registro é obrigatório — prontamente, não enterrado.
• QST nunca entra no líquido. Se você resumir linhas de Quebec, mantenha QST como um valor memo separado. Não adicione QST coletado a net_tax_owing, e não trate QST pago como um ITC.
• Estimativas provinciais são estimativas. Os valores PST/RST da visão provinces e o valor QST em vendas não registradas de Quebec são estimativas taxa×vendas da tabela codificada — nunca os apresente como valores coletados, devidos ou arquivados, e sempre carregue o carimbo de taxas codificadas ("verificadas em 2026-11 — verifique junto às fontes CRA/provinciais antes de arquivar") ao citar as taxas. PST/RST pago sobre insumos nunca é um ITC nesta ferramenta.
• Um líquido negativo é uma posição de reembolso, não renda. Não o descreva como dinheiro recebido.
• Penalidades e juros nunca são computados — se o usuário ultrapassou em um período anterior, isso é uma conversa com a CRA/contador; não estime um valor.
• Apenas local: a ferramenta lê o arquivo para o qual você a aponta e não envia nada para lugar nenhum.