taraz 1.0.0

Professional production-ready double-entry accounting engine for Python with cryptographic audit trails, CSV imports, and IFRS structures.

🌟 Taraz Accounting Engine 🌟

A production-grade, cryptographically secure, and pure Python double-entry accounting engine for automated financial reporting, multi-currency ledger management, cost centers, sub-ledger analytics, and multi-entity consolidation.

---

📖 Overview

Taraz (imported as taraz) is a robust, zero-dependency Python library designed to serve as the core accounting and financial engineering infrastructure for enterprise applications.

With the release of v1.0.0, Taraz matures into a stable, production-ready ledger kernel. It implements high-precision mathematics with Python's native Decimal to eliminate floating-point rounding bugs, and encapsulates advanced sub-ledger functionalities like perpetual inventory costing, invoice matching, year-end currency revaluation, and group consolidations. Additionally, it guarantees audit-trail integrity through automated sequence gap-checking, abnormal balance detection, and SHA-256 cryptographic chain verification.

---

🚀 The Evolutionary Journey: v0.1 to v1.0.0

Taraz was developed incrementally, adding advanced accounting, managerial, and forensic features while preserving full backward compatibility.

🔹 v0.1: The Double-Entry Core

• Introduced basic double-entry bookkeeping entities: AccountType, Account, Posting, and JournalEntry.
• Enforced standard balancing rules (sum of normalized debits must equal credits).
• Implemented basic trial balance and account balance lookups.

🔹 v0.2: Hierarchical Ledger & Fluent API

• Added support for hierarchical charts of accounts (General, Ledger, Sub-ledger, and Subsidiary levels).
• Enabled automatic recursive balance rollups from child accounts to parent accounts without double-counting.
• Introduced a clean, fluent transaction builder (engine.new_entry().debit().credit().post()) for ease of typing.

🔹 v0.3: Liquidity, Leverage, & Closed Periods

• Added standard liquidity and leverage metrics as native engine properties (working_capital, current_ratio, quick_ratio, debt_to_equity_ratio).
• Introduced period locking (set_lock_date) to prevent tampering or back-posting into closed books.

🔹 v0.4: Managerial Segments & Tax Automation

• Introduced Cost Centers (cost_center) to track expenses and revenues by projects or departments.
• Enabled segmented P&L generation (department-wise Income Statements).
• Integrated automated value-added tax (VAT) split posting utilities inside the fluent builder.
• Added native Multi-Currency support, translating foreign currency transactions into the base ledger currency on the fly.

🔹 v0.5: Auditing, Reconciliation, & Aging Analysis

• Implemented Red Storno Reversals to legally offset incorrect transactions with negative values instead of inflating turnover volume.
• Introduced unique posting IDs and matching states (reconciled) for bank statement matching.
• Added Accounts Receivable (A/R) Aging Reports grouping outstanding balances into 0-30, 31-60, 61-90, and 90+ day brackets.
• Integrated sequential document numbering verification to scan for gaps in transaction ranges.

🔹 v0.6: Managerial Budgeting & Tags

• Added transaction Tagging (tags) to filter balances and reports by arbitrary projects or campaigns.
• Introduced budget management and automatic Variance Analysis detecting Favorable (F) and Unfavorable (UF) performance on revenues and expenses.
• Created recurring entry templates to quickly duplicate common operations.

🔹 v0.7: Engineering Economics & GUI Bridges

• Added advanced corporate finance metrics: Net Present Value (NPV), Internal Rate of Return (IRR), WACC, Loan Amortization Schedule generator, and SL/DDB Depreciation methods.
• Built GUI tree structure bridges converting hierarchical charts of accounts (COA) into JSON-ready tree representations suitable for PyQt/PySide QTreeView or Tkinter ttk.Treeview.
• Lazily integrated Matplotlib figure generators to easily embed charts inside desktop screens.

🔹 v0.8: Perpetual Inventory & Cash Flows

• Introduced an independent perpetual Inventory Valuation Engine supporting FIFO, LIFO, and WAVCO (Weighted Average Cost) methods.
• Integrated an automated Statement of Cash Flows (Operating, Investing, Financing activities) based on double-entry balance sheet sheet migrations.

🔹 v0.9: Sub-ledger Clearing & Group Consolidation

• Introduced Invoice-to-Payment Clearing allowing developers to match cash postings against outstanding invoice postings.
• Added automated end-of-period Forex Revaluation adjusting currency balances at a target year-end rate and offsetting variances to Exchange Gain/Loss.
• Created the LedgerConsolidator engine to aggregate independent branch ledgers into a consolidated parent entity.

🔹 v1.0.0: Enterprise Cryptographic Seal (Stable Release)

• Enforced SHA-256 Cryptographic Immutability on the journal ledger. Every transaction stores its own hash combined with the hash of the preceding entry, making any manual database tampering instantly detectable via .verify_ledger_cryptographically().
• Redesigned financial reports to align with official IFRS (IAS 1) standards, distinguishing Current vs Non-Current assets and liabilities.
• Built a robust Bulk CSV Importer to easily ingest transaction tables from other systems (Odoo, ERP systems, Excel templates).

---

⚙️ Installation

pip install taraz

Requires Python 3.8+

---

🛠️ Configuration & Exception Management

All exceptions thrown by Taraz inherit from a structured, clean exceptions tree:

import taraz
from taraz.engine import UnbalancedEntryError, LockedPeriodError

engine = taraz.AccountingEngine()

try:
    # Attempting to post an unbalanced entry
    engine.new_entry("TXN-01", "Imbalanced") \
          .debit("1001", 100) \
          .credit("4001", 50) \
          .post()
except UnbalancedEntryError as e:
    print(f"Post failed: {e}")

---

🚀 Feature Guides & Code Examples

1. Fluent Transaction Builder & Double-Entry Core

Taraz provides a chainable API to speed up manual transaction coding.

from taraz import AccountingEngine, AccountType

engine = AccountingEngine()

# Register Accounts
engine.register_account("1001", "Bank Cash Account", AccountType.ASSET, is_current=True)
engine.register_account("4001", "Sales Revenue", AccountType.REVENUE)

# Record a transaction using the chainable fluent builder API
engine.new_entry("TXN-001", "SaaS License Sale") \
      .debit("1001", "1500.00") \
      .credit("4001", "1500.00") \
      .post()

# Verify balance
print(engine.get_account_balance("1001")) # Output: 1500.00

---

2. Hierarchical Chart of Accounts & Balance Rollups

Track parent-child relationships easily. When querying a parent account, Taraz automatically gathers and summarizes all child account balances dynamically.

from taraz import AccountingEngine, AccountType

engine = AccountingEngine()

# Parent Asset account
engine.register_account("1000", "Total Assets", AccountType.ASSET)

# Child Accounts (inherits Asset type from parent)
engine.register_account("1001", "Bank cash", AccountType.ASSET, parent_code="1000")
engine.register_account("1002", "Petty cash", AccountType.ASSET, parent_code="1000")

# Post a debit to petty cash
engine.new_entry("TXN-001", "Replenish petty cash") \
      .debit("1002", "200.00") \
      .credit("1001", "200.00") \
      .post()

# Query parent account balance - it automatically sums up child balances!
print(engine.get_account_balance("1000")) # Output: 0.00 (Total assets didn't change, cash moved within children)

---

3. IFRS-Compliant Structured Financial Statements

Generate IFRS-compliant reports classified under Current vs Non-Current listings automatically.

from taraz import AccountingEngine, AccountType

engine = AccountingEngine()

# Register IFRS-tagged accounts
engine.register_account("1001", "Cash at Bank", AccountType.ASSET, is_current=True)
engine.register_account("1500", "Warehouse Property", AccountType.ASSET, is_current=False)
engine.register_account("2001", "Accounts Payable", AccountType.LIABILITY, is_current=True)
engine.register_account("3000", "Capital Equity", AccountType.EQUITY)

# Post Investment
engine.new_entry("TXN-01", "Equity Funding") \
      .debit("1001", "10000.00") \
      .credit("3000", "10000.00") \
      .post()

# Generate the Structured IFRS Balance Sheet
balance_sheet = engine.generate_balance_sheet()

print(balance_sheet["total_current_assets"])      # Output: 10000.00
print(balance_sheet["total_non_current_assets"])  # Output: 0.00
print(balance_sheet["is_balanced"])               # Output: True

---

4. Managerial Segments & Budgeting

Monitor departmental profitability and compare actual performance against predefined budget boundaries.

from taraz import AccountingEngine, AccountType
from datetime import datetime

engine = AccountingEngine()
engine.register_account("1001", "Bank", AccountType.ASSET)
engine.register_account("5001", "Advertising Costs", AccountType.EXPENSE)

# Set budget bounds for marketing
start_date = datetime(2026, 1, 1)
end_date = datetime(2026, 1, 31)
engine.set_budget("5001", "500.00", start_date, end_date)

# Record actual expense associated with Marketing department cost center
engine.new_entry("ADV-JAN", "Google Ad campaign", date=datetime(2026, 1, 15)) \
      .debit("5001", "600.00", cost_center="MKT-DEPT") \
      .credit("1001", "600.00") \
      .post()

# Perform Variance Analysis
report = engine.get_budget_variance("5001", start_date, end_date)
print(report["variance"]) # Output: 100.00
print(report["status"])   # Output: "Unfavorable" (spent more than budgeted)

---

5. Multi-Currency Accounting & End-of-Period Revaluation

Record transactions in arbitrary currencies. Taraz automatically evaluates balances and recalculates assets based on new rates in closed periods.

from taraz import AccountingEngine, AccountType

engine = AccountingEngine()
engine.register_account("1001", "Bank EUR Account", AccountType.ASSET)
engine.register_account("4001", "Revenue", AccountType.REVENUE)
engine.register_account("8001", "Exchange Gain/Loss", AccountType.REVENUE) # Normal Credit

# Received 1000 EUR @ 1.10 rate = $1100 historical base value
engine.new_entry("TXN-EUR", "European invoice payment") \
      .debit("1001", "1000.00", currency="EUR", exchange_rate="1.10") \
      .credit("4001", "1100.00") \
      .post()

# At year-end, the EUR exchange rate increases to 1.15. Revalue!
engine.revalue_currency_account(
    account_code="1001",
    target_currency="EUR",
    current_rate="1.15",
    gain_loss_account_code="8001",
    entry_id="YREND-REVAL"
)

# Valuation must now reflect current exchange rates
print(engine.get_account_balance("1001")) # Output: 1150.00
print(engine.get_account_balance("8001")) # Output: 50.00 (Gain recognized)

---

6. Sub-ledger Accounts Receivable Clearing

Match cash payment postings against target invoice postings.

from taraz import AccountingEngine, AccountType

engine = AccountingEngine()
engine.register_account("1200", "Receivables", AccountType.ASSET)
engine.register_account("1001", "Bank", AccountType.ASSET)
engine.register_account("4001", "Revenue", AccountType.REVENUE)

# 1. Post Sale Invoice
inv_entry = engine.new_entry("INV-01", "Invoice 1") \
                  .debit("1200", "500.00") \
                  .credit("4001", "500.00") \
                  .post()
invoice_posting_id = inv_entry.postings[0].posting_id

# 2. Post Cash Receipt
pay_entry = engine.new_entry("PAY-01", "Partial Payment") \
                  .debit("1001", "300.00") \
                  .credit("1200", "300.00") \
                  .post()
payment_posting_id = pay_entry.postings[1].posting_id

# Match postings (clear partial payment against invoice)
engine.match_postings(invoice_posting_id, payment_posting_id, "300.00")

# Check remaining unmatched amount on invoice
print(engine.get_unmatched_amount(invoice_posting_id)) # Output: 200.00

---

7. Perpetual Inventory Costing (FIFO, LIFO, WAVCO)

The separate valuation module manages inventory costing methods natively.

from taraz import InventoryValuationEngine

inv = InventoryValuationEngine()

# Buy Batch 1: 10 units @ $10.00
inv.record_purchase("SKU-PRO", 10, "10.00")
# Buy Batch 2: 10 units @ $15.00
inv.record_purchase("SKU-PRO", 10, "15.00")

# Sell 12 units using FIFO method
cogs, ending_value = inv.record_sale("SKU-PRO", 12, method="FIFO")

# FIFO logic consumes: 10 units @ 10 + 2 units @ 15 = $130
print(cogs)         # Output: 130.00
print(ending_value) # Output: 120.00 (8 remaining units @ 15)

---

8. Auditing: Cryptographic Immutability & Sequence Gap Checking

Prevent SQL tampering or back-posting.

from taraz import AccountingEngine, AccountType

engine = AccountingEngine()
engine.register_account("1001", "Bank", AccountType.ASSET)
engine.register_account("4001", "Revenue", AccountType.REVENUE)

# Post genuine transaction
engine.new_entry("INV-1", "Genuine Sale").debit("1001", 100).credit("4001", 100).post()

# Verify cryptographic ledger state
print(engine.verify_ledger_cryptographically()) # Output: True

# Malicious modification bypassing the engine
engine.journal[0].postings[0].debit = 9999.00

# Verification fails instantly!
print(engine.verify_ledger_cryptographically()) # Output: False

---

9. Dev Utilities: Bulk CSV Importing & Group Consolidation

Easily import historical data and consolidate group companies.

from taraz import AccountingEngine, LedgerConsolidator, DevUtils

# Import transactions from a standard formatted CSV file
engine_subsidiary = AccountingEngine()
engine_subsidiary.register_account("1001", "Bank USD", taraz.AccountType.ASSET)
engine_subsidiary.register_account("4001", "Revenue", taraz.AccountType.REVENUE)

DevUtils.import_journal_from_csv(engine_subsidiary, "historical_data.csv")

# Consolidate multiple corporate entities into a parent ledger
engine_parent = AccountingEngine()
consolidated_engine = LedgerConsolidator.consolidate([engine_subsidiary], parent_engine=engine_parent)

---

🧪 Running Tests

Taraz ships with a robust unit testing suite covering all accounting, analytics, and cryptographic functionalities:

python -m unittest tests/test_taraz.py

---

👨‍💻 Author

Ali Kamrani

• GitHub: @MRThugh
• Email: [e-mail]

---

📄 License

This project is licensed under the MIT License. You are free to copy, modify, and distribute Taraz in your commercial or open-source products.

---

Taraz — High-precision cryptographic accounting infrastructure for Python developers. 🚀