Metadata-Version: 2.4
Name: taraz
Version: 1.0.0
Summary: Professional production-ready double-entry accounting engine for Python with cryptographic audit trails, CSV imports, and IFRS structures.
Home-page: https://github.com/MRThugh/taraz
Author: Ali Kamrani
Author-email: Ali Kamrani <kamrani.exe@gmail.com>
Project-URL: Homepage, https://github.com/MRThugh
Project-URL: Source, https://github.com/MRThugh/taraz
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Office/Business :: Financial :: Accounting
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

<div align="center">

# 🌟 Taraz Accounting Engine 🌟
<p align="center">
  <img 
    src="https://raw.githubusercontent.com/MRThugh/MRThugh/main/badge.svg"
    width="50%" 
  />
</p>

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Author](https://img.shields.io/badge/author-Ali%20Kamrani-purple.svg)](https://github.com/MRThugh)
[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/MRThugh/taraz)

**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.**

</div>

---

## 📖 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

```bash
pip install taraz
```

**Requires Python 3.8+**

---

## 🛠️ Configuration & Exception Management

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

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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:

```bash
python -m unittest tests/test_taraz.py
```

---

## 👨‍💻 Author

**Ali Kamrani**

- GitHub: [@MRThugh](https://github.com/MRThugh)
- Email: kamrani.exe@gmail.com

---

## 📄 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. 🚀
