gst-hst-tracker — 에이전트 스킬
목적
캐나다 프리랜서와 개인사업자는 스프레드시트에서 GST/HST를 추적하고, CRA의 $30,000 소규모 공급자 임계값을 초과한 후에야 알게 됩니다. 이 도구는 날짜가 있는 거래 원장을 읽어 (a) 분기별 GST/HST 징수액, ITC 및 순 납부세액과 함께 T2125 스타일의 소득/비용 준비 섹션, (b) 임계값 테스트: 최근 4개 역년 분기의 과세 소득을 $30,000 한도와 비교하여 여유 공간 또는 초과 경보, (c) 동일한 원장의 주별 보기: 세금 체계, 징수액, ITC 및 주별 순액을 제공합니다(주별 구성 요소는 데이터가 지원하는 범위 내에서만 표시: 기록된 QST는 메모 수치로, 기록되지 않은 QC 판매에 대한 추정치 포함; PST/RST는 세율×매출 노출 추정치). 순수 Python 표준 라이브러리, 로컬 전용, 하나의 원장 파일 읽기, 기록하지 않음.
이 도구의 핵심 정직성: 추적 및 계산 보조 도구이며, 세무 조언이 아니며 CRA 신고도 아닙니다. 모든 보고서에는 이 면책 문구가 포함되며, 그 출력물을 바탕으로 작성하는 모든 내용에도 동일한 문구가 포함되어야 합니다. 벌금이나 이자를 계산하지 않습니다.
사용 시기 / 사용하지 말아야 할 시기
다음과 같은 경우 사용:
- 거래 원장에서 분기의 GST/HST 수치 준비: 징수액, ITC, 순 납부액.
- 프리랜서가 $30,000 등록 임계값에 얼마나 가까운지 확인하거나 초과했는지 확인.
- 신고 시즌을 위해 소득 및 비용 범주를 T2125 스타일 준비 보기로 구성.
- 에이전트가 신뢰할 수 있는 캐나다 GST/HST 숫자를 JSON 형식으로 필요로 할 때.
다음과 같은 경우 사용하지 않음:
- 사용자가 세무 조언, 신고, 또는 의무에 대한 판정을 필요로 하는 경우 — 이 도구는 제공할 수 없습니다. CRA 또는 자격을 갖춘 회계사에게 안내하십시오.
- 질문에 벌금 또는 이자가 포함된 경우 — 계산되지 않음.
- 장부가 퀘벡 QST 장부인 경우: QST는 여기서 메모 전용입니다(한계 참조). BC PST / SK PST / MB RST는
provinces보기에서 노출 추정치로만 나타납니다 — 납부 세액이나 공제로 표시되지 않습니다. - 원장이 오래된 경우: 임계값 창은 최신 거래에 고정되므로 오래된 원장은 오래된 창을 제공합니다. 날짜가 오래된 것으로 보이면 그렇게 말하십시오.
설치
pipx install git+https://github.com/jasveerai88/gst-hst-tracker
# 또는: pip install git+https://github.com/jasveerai88/gst-hst-tracker
(PyPI에 없음 — git+ 형식이 설치입니다.) 소스 체크아웃에서 python3 src/gst_hst_tracker.py ...도 동일합니다.
명령어
# 분기별 보고서 (JSON 또는 CSV 입력, 성공 시 종료 코드 0)
gst-hst-tracker report LEDGER.json
gst-hst-tracker report LEDGER.csv --json
# 특정 분기 또는 연도만
gst-hst-tracker report LEDGER.json --period 2026-Q1
gst-hst-tracker report LEDGER.json --period 2026
# 소규모 공급자 경보 (초과 시 종료 코드 1, 그 외 0)
gst-hst-tracker threshold LEDGER.json [--limit 30000]
# 주별 보기 (성공 시 종료 코드 0)
gst-hst-tracker provinces LEDGER.json
gst-hst-tracker provinces LEDGER.json --period 2026-Q1 --json
# INR 등가액도 표시 (1 CAD당 환율)
gst-hst-tracker report LEDGER.json --cad-to-inr 67.97
# 주 세율 변경 시 재정의
gst-hst-tracker report LEDGER.json --rate NS=15
입력 행 (JSON 목록, {"transactions": [...]} 객체, 또는 동일한 헤더를 가진 CSV): date (YYYY-MM-DD, 필수), kind (income|expense, 필수), description (필수), amount (세전 CAD, 필수, ≥ 0), province (두 글자 코드, 필수); 선택 사항 tax (부과/지불된 GST/HST — 생략 시 주 세율로 계산; 0은 영세율을 의미하며 존중됨), qst (QC 행만 해당, 별도 추적, 순액에 포함되지 않음), category (비용만 해당, T2125 스타일 그룹화).
모델 (결과를 보고할 때 명시)
- 역년 분기별 순 납부세액 = 소득에 대한 GST/HST 징수액 − ITC(비용에 대해 지불된 GST/HST). 음의 순액 = ITC가 징수액 초과: 환급 상태, 현금 보유가 아님.
- 임계값: 최근 4개 역년 분기(최신 거래 분기 종료) 동안의 과세 공급(소득 행만). CRA의 테스트는 초과 $30,000 — 정확히 $30,000는 여전히 소규모 공급자(
status: "at", 종료 코드 0). - 2026년 11월 기준 기본 세율: GST 5% (AB BC MB NT NU SK YT), HST 13% ON, HST 15% NB/NL/PE, HST 14% NS (2025-04-01부터 15%에서 인하), QC = GST 5% 연방 부분만.
- QST (9.975%)는 별도의 Revenu Québec 세금: 제공된
qst금액은 메모 합계로만 나타나며 순액에 포함되지 않습니다. - 주별 보기 (
provinces): 동일한 연방 수학을 행의 주별로 그룹화. 인코딩된 주 세율, "인코딩된 세율, 2026-11 확인 — 신고 전 CRA/주 세무 당국에 확인" 스탬프 포함: QST 9.975% (QC), PST 7% (BC), PST 6% (SK), RST 7% (MB); HST 주에는 별도의 주 구성 요소가 없습니다. QC는 기록된 QST 합계와 기록된qst가 없는 QC 소득 행에 대한 추정치를 표시; BC/SK/MB는 세율×매출 노출 추정치만 표시하며 주 ITC는 없음(PST/RST는 일반적으로 비용). 반올림: 주별 수치는 센트 단위로 반올림되며 합계는 반올림된 수치를 합산하므로 항상 주 블록과 일치합니다.
출력 JSON 스키마 (--json)
report: tool ("gst-hst-tracker"), version, command ("report"), file, currency ("CAD"), rates (주별 rate_pct + 레이블, as_of: "2026-11" 스탬프 및 QST 참고 사항 포함), cad_to_inr (환율 또는 null), period_filter (문자열 또는 null), periods, totals, disclaimer.
각 기간: period (예: "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는 표시된 기간 동안 동일한 필드를 합산합니다. --cad-to-inr 사용 시 금액 필드에 *_inr 자매 필드가 추가됩니다.
threshold: 공통 필드에 추가로 latest_transaction, window_end_quarter, quarters (네 개의 {quarter, income} 항목, 가장 오래된 순), rolling_total, limit, headroom (초과 시 0), over_by (초과하지 않은 경우 0), crossed (bool), status ("under" | "at" | "crossed"), rule, disclaimer.
provinces: 공통 필드에 추가로 provincial_rates (stamp, qst_rate_pct, taxes — 주별 federal 레이블 및 provincial_tax {name, rate_pct} 또는 null), rounding_rule, provinces, totals, disclaimer. provinces의 각 항목: province, tax_system (유효 세율로 구성, 예: "GST 5% + PST 7%"), income_total, expense_total, gst_hst_collected, itcs, net_tax_owing, transactions, 및 provincial — GST 전용 및 HST 주는 null, 그 외: {name, rate_pct, recorded_collected, recorded_paid, recorded_net} (QC는 숫자, BC/SK/MB는 null — 해당 주에 대해 기록된 것 없음), estimate_base, estimated_on_sales, note. totals는 qst_recorded_collected / qst_recorded_paid / qst_recorded_net 및 provincial_estimated_on_sales를 추가합니다.
오류 발생 시 stdout은 단일 객체: {"error": "<message>"} (유효성 검사 오류는 행 이름 지정: "row 2: ...")이며 종료 코드 2 — --json 모드에서 argparse 사용 오류 포함. 일반 텍스트나 역추적(traceback) 없음.
종료 코드
report:0— 보고서 계산됨.2— 오류.provinces:0— 보기 계산됨.2— 오류. (종료 코드 1 상태 없음: 보기는 정보 제공 목적이며 경보는threshold에 있음.)threshold:0— 롤링 합계가 한도 미만 또는 정확히 한도: 이 수치로는 여전히 소규모 공급자.1— 임계값 초과: 롤링 합계가 한도를 초과하여 GST/HST 등록이 필요합니다. 이는 실패가 아니라 결과입니다: 눈에 띄게 표시하십시오.2— 오류: 숫자가 생성되지 않았습니다. 어떤 것도 인용하지 마십시오.- 두 명령어 모두 오류 시 종료 코드
2와 함께 깔끔한 메시지(또는--json모드에서는{"error": ...}객체)를 반환합니다.
에이전트가 반드시 준수해야 할 한계 및 정직성 규칙
- 세무 조언이 아니며 신고도 아닙니다. 이 도구의 출력을 조언이나 신고된 신고서로 제시하지 마십시오. 모든 출력의 면책 문구는 중요합니다: 작성하는 모든 요약에 첨부하십시오.
- 세율은 2026년 11월의 기본값이며 실시간 사실이 아닙니다. "도구의 2026년 11월 기본값"으로 인용하고 재정의 가능함을 명시하십시오. 노바스코샤는 14%입니다(2025-03-31까지 15%였음) — 사용자의 수치가 NS에 대해 15%로 계산되었다면, 조용히 수용하지 말고 플래그를 지정할 가치가 있습니다.
- 정확히 $30,000는 초과가 아닙니다. CRA의 테스트는 "$30,000 초과"입니다.
status가"at"인 경우 "여유 공간 없이 여전히 소규모 공급자"로 보고하십시오 — "반드시 등록해야 함"이라고 하지 마십시오. threshold의 종료 코드 1은 도구가 작동 중임을 의미합니다. 경보가 발생했음을 의미합니다. 롤링 합계, 초과 금액 및 등록이 필요함을 신속하게 보고하십시오 — 묻히지 않도록.- QST는 순액에 포함되지 않습니다. 퀘벡 행을 요약하는 경우 QST를 별도의 메모 수치로 유지하십시오. 징수된 QST를
net_tax_owing에 추가하지 말고, 지불된 QST를 ITC로 취급하지 마십시오. - 주별 추정치는 추정치입니다.
provinces보기의 PST/RST 수치와 기록되지 않은 퀘벡 판매에 대한 QST 수치는 인코딩된 테이블의 세율×매출 추정치입니다 — 징수액, 납부액 또는 신고액으로 제시하지 말고, 세율을 인용할 때 항상 인코딩된 세율 스탬프("2026-11 확인 — 신고 전 CRA/주 세무 당국에 확인")를 함께 표시하십시오. 투입에 대해 지불된 PST/RST는 이 도구에서 ITC가 아닙니다. - 음의 순액은 환급 상태이며 소득이 아닙니다. 수령한 돈으로 설명하지 마십시오.
- 벌금과 이자는 계산되지 않습니다 — 사용자가 이전 기간에 임계값을 초과한 경우, 이는 CRA/회계사와의 상담 사항입니다. 금액을 추정하지 마십시오.
- 로컬 전용: 도구는 사용자가 가리키는 파일을 읽고 아무 곳에도 전송하지 않습니다.