lambda-erp 0.1.0__py3-none-any.whl

lambda_erp/accounting/budget.py

@@ -0,0 +1,117 @@
+"""
+Budget.
+
+Budget defines an annual spending limit for an account + cost center.
+When GL entries are posted, validate_expense_against_budget() checks
+whether the new expense would exceed the budget and raises an error
+(Stop) or warning (Warn) accordingly.
+"""
+
+from lambda_erp.model import Document
+from lambda_erp.utils import _dict, flt, getdate, nowdate
+from lambda_erp.database import get_db
+from lambda_erp.exceptions import ValidationError
+
+import warnings
+
+class Budget(Document):
+    DOCTYPE = "Budget"
+    CHILD_TABLES = {
+        "monthly_distribution": ("Monthly Distribution", None),
+    }
+    PREFIX = "BDG"
+
+    def validate(self):
+        if not self.account:
+            raise ValidationError("Account is required")
+        if not self.fiscal_year:
+            raise ValidationError("Fiscal Year is required")
+        if not self.company:
+            raise ValidationError("Company is required")
+        if flt(self.budget_amount) <= 0:
+            raise ValidationError("Budget Amount must be greater than 0")
+
+        if not self.cost_center:
+            db = get_db()
+            self._data["cost_center"] = db.get_value(
+                "Company", self.company, "default_cost_center"
+            )
+
+        if not self._data.get("action_if_exceeded"):
+            self._data["action_if_exceeded"] = "Warn"
+
+def validate_expense_against_budget(gl_entry):
+    """Check if a GL entry would exceed any active budget.
+
+    Called from make_gl_entries() in general_ledger.py before saving.
+    Only checks debit entries to expense accounts.
+    """
+    debit = flt(gl_entry.get("debit", 0))
+    if debit <= 0:
+        return
+
+    account = gl_entry.get("account")
+    if not account:
+        return
+
+    db = get_db()
+
+    # Only check expense accounts (root_type = Expense)
+    account_data = db.get_value("Account", account, ["root_type", "is_group"])
+    if not account_data or account_data.root_type != "Expense":
+        return
+
+    cost_center = gl_entry.get("cost_center")
+    company = gl_entry.get("company")
+    posting_date = gl_entry.get("posting_date") or nowdate()
+
+    # Determine fiscal year from posting date
+    year = getdate(posting_date).year
+
+    # Find matching budgets
+    filters = {"account": account, "company": company}
+    if cost_center:
+        filters["cost_center"] = cost_center
+
+    budgets = db.get_all("Budget", filters=filters, fields=["*"])
+
+    for budget in budgets:
+        budget_amount = flt(budget.get("budget_amount", 0))
+        if budget_amount <= 0:
+            continue
+
+        fiscal_year = budget.get("fiscal_year", "")
+        if fiscal_year and str(year) not in fiscal_year:
+            continue
+
+        # Sum existing expenses for this account + cost_center in this year
+        start_date = f"{year}-01-01"
+        end_date = f"{year}-12-31"
+
+        result = db.sql(
+            """
+            SELECT COALESCE(SUM(debit), 0) - COALESCE(SUM(credit), 0) as total
+            FROM "GL Entry"
+            WHERE account = ?
+              AND company = ?
+              AND posting_date >= ? AND posting_date <= ?
+              AND is_cancelled = 0
+            """,
+            [account, company, start_date, end_date],
+        )
+
+        actual_expense = flt(result[0].get("total", 0)) if result else 0
+        total_with_new = actual_expense + debit
+
+        action = budget.get("action_if_exceeded", "Warn")
+
+        if total_with_new > budget_amount:
+            msg = (
+                f"Budget exceeded for {account}: "
+                f"Budget {budget_amount:.2f}, "
+                f"Actual {actual_expense:.2f} + New {debit:.2f} = {total_with_new:.2f}"
+            )
+            if action == "Stop":
+                raise ValidationError(msg)
+            elif action == "Warn":
+                warnings.warn(msg)

lambda_erp/accounting/chart_of_accounts.py

@@ -0,0 +1,183 @@
+"""
+Standard Chart of Accounts setup.
+
+In the reference implementation, the Chart of Accounts is a tree structure defined in JSON files
+under reference_impl/accounts/doctype/account/chart_of_accounts/. Each country
+has its own chart.
+
+This module provides a simplified standard chart that covers the essential
+account types needed for a working ERP system.
+"""
+
+from lambda_erp.utils import _dict, new_name
+from lambda_erp.database import get_db
+
+
+# Standard chart of accounts - matches the essential structure from the reference implementation
+STANDARD_CHART = {
+    "Assets": {
+        "root_type": "Asset",
+        "report_type": "Balance Sheet",
+        "children": {
+            "Current Assets": {
+                "children": {
+                    "Accounts Receivable": {
+                        "account_type": "Receivable",
+                    },
+                    "Bank Accounts": {
+                        "children": {
+                            "Primary Bank": {"account_type": "Bank"},
+                        }
+                    },
+                    "Cash": {"account_type": "Cash"},
+                    "Stock In Hand": {"account_type": "Stock"},
+                    "Stock Received But Not Billed": {
+                        "account_type": "Stock Received But Not Billed",
+                    },
+                }
+            },
+            "Fixed Assets": {
+                "children": {
+                    "Fixed Asset Account": {"account_type": "Fixed Asset"},
+                    "Accumulated Depreciation": {
+                        "account_type": "Accumulated Depreciation",
+                    },
+                }
+            },
+        },
+    },
+    "Liabilities": {
+        "root_type": "Liability",
+        "report_type": "Balance Sheet",
+        "children": {
+            "Current Liabilities": {
+                "children": {
+                    "Accounts Payable": {"account_type": "Payable"},
+                    "Tax Payable": {"account_type": "Tax"},
+                    "Salary Payable": {"account_type": "Payable"},
+                }
+            },
+        },
+    },
+    "Equity": {
+        "root_type": "Equity",
+        "report_type": "Balance Sheet",
+        "children": {
+            "Opening Balance Equity": {},
+            "Retained Earnings": {},
+        },
+    },
+    "Income": {
+        "root_type": "Income",
+        "report_type": "Profit and Loss",
+        "children": {
+            "Sales Revenue": {"account_type": "Income Account"},
+            "Service Revenue": {"account_type": "Income Account"},
+            "Other Income": {},
+        },
+    },
+    "Expenses": {
+        "root_type": "Expense",
+        "report_type": "Profit and Loss",
+        "children": {
+            "Cost of Goods Sold": {"account_type": "Cost of Goods Sold"},
+            "Operating Expenses": {
+                "children": {
+                    "Administrative Expenses": {},
+                    "Marketing Expenses": {},
+                    "Salary Expense": {},
+                    # Standard charge accounts for supplier-invoice charges
+                    # that aren't item lines — freight/shipping, customs,
+                    # import duties. Referenced via Company.default_* so the
+                    # chat (or a human) has a sensible target when parsing
+                    # a supplier bill with those charges on it.
+                    "Freight In": {"account_type": "Chargeable"},
+                    "Customs & Duties": {"account_type": "Chargeable"},
+                    # Realized FX gain/loss on settling foreign-currency
+                    # invoices (Payment Entry). Net of debits (losses) and
+                    # credits (gains); sits in P&L.
+                    "Exchange Gain/Loss": {},
+                    # Unrealized FX from period-end revaluation of open foreign
+                    # monetary balances. Posted at period end and reversed the
+                    # next period (kept separate from realized for reporting).
+                    "Unrealized Exchange Gain/Loss": {},
+                }
+            },
+            "Depreciation Expense": {"account_type": "Depreciation"},
+            "Stock Adjustment": {"account_type": "Stock Adjustment"},
+            "Round Off": {"account_type": "Round Off"},
+        },
+    },
+}
+
+
+def setup_chart_of_accounts(company_name, currency="USD"):
+    """Create all accounts for a company from the standard chart.
+
+    This mirrors the reference implementation's setup wizard step that creates the Chart of Accounts
+    from a template when a new company is created.
+    """
+    db = get_db()
+
+    def _create_accounts(tree, parent=None, root_type=None, report_type=None):
+        for account_name, details in tree.items():
+            rt = details.get("root_type", root_type)
+            rpt = details.get("report_type", report_type)
+            has_children = "children" in details
+
+            name = f"{account_name} - {company_name[:4].upper()}"
+
+            account = _dict(
+                name=name,
+                account_name=account_name,
+                parent_account=parent,
+                company=company_name,
+                root_type=rt,
+                report_type=rpt,
+                account_type=details.get("account_type", ""),
+                account_currency=currency,
+                is_group=1 if has_children else 0,
+            )
+            db.insert("Account", account)
+
+            if has_children:
+                _create_accounts(details["children"], parent=name, root_type=rt, report_type=rpt)
+
+    _create_accounts(STANDARD_CHART)
+
+    # Set up company defaults
+    abbr = company_name[:4].upper()
+    db.set_value("Company", company_name, {
+        "default_receivable_account": f"Accounts Receivable - {abbr}",
+        "default_payable_account": f"Accounts Payable - {abbr}",
+        "default_income_account": f"Sales Revenue - {abbr}",
+        "default_expense_account": f"Cost of Goods Sold - {abbr}",
+        "round_off_account": f"Round Off - {abbr}",
+        "stock_in_hand_account": f"Stock In Hand - {abbr}",
+        "stock_received_but_not_billed": f"Stock Received But Not Billed - {abbr}",
+        "stock_adjustment_account": f"Stock Adjustment - {abbr}",
+        "default_opening_balance_equity": f"Opening Balance Equity - {abbr}",
+        "default_freight_in_account": f"Freight In - {abbr}",
+        "default_customs_account": f"Customs & Duties - {abbr}",
+        "default_exchange_gain_loss_account": f"Exchange Gain/Loss - {abbr}",
+        "default_unrealized_exchange_account": f"Unrealized Exchange Gain/Loss - {abbr}",
+    })
+
+    db.commit()
+    return True
+
+
+def setup_cost_center(company_name):
+    """Create default cost center for a company."""
+    db = get_db()
+    name = f"Main - {company_name[:4].upper()}"
+    db.insert("Cost Center", _dict(
+        name=name,
+        cost_center_name="Main",
+        company=company_name,
+        is_group=0,
+    ))
+    db.set_value("Company", company_name, "default_cost_center", name)
+    db.set_value("Company", company_name, "round_off_cost_center", name)
+    db.commit()
+    return name

lambda_erp/accounting/general_ledger.py

@@ -0,0 +1,362 @@
+"""
+General Ledger entry creation engine.
+
+The heart of double-entry bookkeeping. Every financial transaction ultimately
+calls make_gl_entries() to post debit/credit entries to the General Ledger.
+
+Key invariant: total debits MUST equal total credits for every voucher.
+
+The flow:
+  Document.on_submit() -> make_gl_entries(gl_map)
+    -> process_gl_map() (merge similar entries)
+    -> toggle_debit_credit_if_negative()
+    -> process_debit_credit_difference() (round-off adjustment)
+    -> save_entries() (persist to DB)
+"""
+
+import copy
+from lambda_erp.utils import _dict, flt, new_name, now
+from lambda_erp.database import get_db
+from lambda_erp.exceptions import DebitCreditNotEqual, InvalidAccountError
+
+def make_gl_entries(gl_map, cancel=False, merge_entries=True):
+    """Create GL entries from a list of GL entry dicts.
+
+    This is the main entry point, called by every document that affects
+    the accounting ledger (invoices, payments, journal entries, stock entries
+    with perpetual inventory, etc.).
+
+    Args:
+        gl_map: list of _dict with keys like account, debit, credit,
+                voucher_type, voucher_no, posting_date, company, etc.
+        cancel: if True, create reversing entries instead
+        merge_entries: if True, merge entries with same account/party/etc.
+    """
+    if not gl_map:
+        return
+
+    if cancel:
+        make_reverse_gl_entries(gl_map)
+        return
+
+    gl_map = process_gl_map(gl_map, merge_entries)
+
+    if gl_map and len(gl_map) > 1:
+        process_debit_credit_difference(gl_map)
+        validate_disabled_accounts(gl_map)
+
+        # Budget check — validate expense entries before saving
+        from lambda_erp.accounting.budget import validate_expense_against_budget
+        for entry in gl_map:
+            validate_expense_against_budget(entry)
+
+        save_entries(gl_map)
+    elif gl_map:
+        raise InvalidAccountError(
+            "Incorrect number of General Ledger Entries found. "
+            "You might have selected a wrong Account in the transaction."
+        )
+
+def to_base_currency(gl_entries, conversion_rate):
+    """Scale document-currency GL amounts to the company's base currency.
+
+    Financial GL entries are built in document currency (debit ==
+    debit_in_account_currency). The ledger's debit/credit columns must be in
+    the company's base/functional currency, so multiply them by conversion_rate
+    while leaving the *_in_account_currency amounts in document currency.
+
+    Only pass financial entries (AR/AP, income/expense, tax, payments) through
+    this. Cost-of-goods / stock entries are already valued in base currency and
+    must NOT be re-scaled. A rate of 1.0 (single-currency, the default) is a
+    no-op, so existing single-currency books are untouched.
+    """
+    rate = flt(conversion_rate) or 1.0
+    if rate == 1.0:
+        return gl_entries
+    for entry in gl_entries:
+        entry["debit"] = flt(flt(entry.get("debit", 0)) * rate, 2)
+        entry["credit"] = flt(flt(entry.get("credit", 0)) * rate, 2)
+    return gl_entries
+
+
+def process_gl_map(gl_map, merge_entries=True):
+    """Process the GL entry map: merge similar entries, fix negative values."""
+    if not gl_map:
+        return []
+
+    if merge_entries:
+        gl_map = merge_similar_entries(gl_map)
+
+    gl_map = toggle_debit_credit_if_negative(gl_map)
+
+    return gl_map
+
+def merge_similar_entries(gl_map):
+    """Merge GL entries that have the same account + party + voucher_detail.
+
+    This is important because a single invoice might have multiple items
+    hitting the same income account - we want one consolidated GL entry.
+    """
+    merged = []
+    merge_keys = [
+        "account", "cost_center", "party", "party_type",
+        "against_voucher", "against_voucher_type", "voucher_no"
+    ]
+
+    for entry in gl_map:
+        key = tuple(entry.get(k, "") for k in merge_keys)
+        entry["_merge_key"] = key
+
+        same_head = None
+        for existing in merged:
+            if existing.get("_merge_key") == key:
+                same_head = existing
+                break
+
+        if same_head:
+            same_head["debit"] = flt(same_head["debit"]) + flt(entry.get("debit", 0))
+            same_head["credit"] = flt(same_head["credit"]) + flt(entry.get("credit", 0))
+            same_head["debit_in_account_currency"] = (
+                flt(same_head.get("debit_in_account_currency", 0))
+                + flt(entry.get("debit_in_account_currency", 0))
+            )
+            same_head["credit_in_account_currency"] = (
+                flt(same_head.get("credit_in_account_currency", 0))
+                + flt(entry.get("credit_in_account_currency", 0))
+            )
+        else:
+            merged.append(entry)
+
+    # Filter zero entries
+    merged = [e for e in merged if flt(e.get("debit"), 2) != 0 or flt(e.get("credit"), 2) != 0]
+
+    return merged
+
+def toggle_debit_credit_if_negative(gl_map):
+    """If debit is negative, move it to credit and vice versa.
+
+    Ensures all GL entries have non-negative debit and credit values.
+    """
+    for entry in gl_map:
+        debit = flt(entry.get("debit", 0))
+        credit = flt(entry.get("credit", 0))
+
+        if debit < 0:
+            credit = credit - debit
+            debit = 0.0
+
+        if credit < 0:
+            debit = debit - credit
+            credit = 0.0
+
+        entry["debit"] = flt(debit, 2)
+        entry["credit"] = flt(credit, 2)
+
+        # Same for account currency amounts
+        debit_acc = flt(entry.get("debit_in_account_currency", 0))
+        credit_acc = flt(entry.get("credit_in_account_currency", 0))
+
+        if debit_acc < 0:
+            credit_acc = credit_acc - debit_acc
+            debit_acc = 0.0
+        if credit_acc < 0:
+            debit_acc = debit_acc - credit_acc
+            credit_acc = 0.0
+
+        entry["debit_in_account_currency"] = flt(debit_acc, 2)
+        entry["credit_in_account_currency"] = flt(credit_acc, 2)
+
+    return gl_map
+
+def process_debit_credit_difference(gl_map):
+    """Ensure total debits == total credits, adding round-off entry if needed.
+
+    This is the double-entry bookkeeping integrity check. Due to rounding,
+    there can be small differences which are posted to a round-off account.
+    """
+    precision = 2
+    debit_credit_diff = sum(
+        flt(e.get("debit", 0), precision) - flt(e.get("credit", 0), precision)
+        for e in gl_map
+    )
+    debit_credit_diff = flt(debit_credit_diff, precision)
+
+    allowance = 0.5  # the reference implementation allows 0.5 for non-JE/PE documents
+
+    if abs(debit_credit_diff) > allowance:
+        raise DebitCreditNotEqual(
+            f"Debit and Credit not equal for {gl_map[0].get('voucher_type')} "
+            f"#{gl_map[0].get('voucher_no')}. Difference is {debit_credit_diff}."
+        )
+
+    # Add round-off entry if there's a small difference
+    if abs(debit_credit_diff) >= 0.01:
+        db = get_db()
+        company = gl_map[0].get("company")
+        round_off_account = db.get_value("Company", company, "round_off_account")
+        round_off_cost_center = db.get_value("Company", company, "round_off_cost_center")
+
+        if not round_off_account:
+            round_off_account = db.get_value("Company", company, "default_expense_account")
+
+        if round_off_account:
+            gl_map.append(
+                _dict(
+                    account=round_off_account,
+                    cost_center=round_off_cost_center,
+                    debit=abs(debit_credit_diff) if debit_credit_diff < 0 else 0,
+                    credit=debit_credit_diff if debit_credit_diff > 0 else 0,
+                    debit_in_account_currency=abs(debit_credit_diff) if debit_credit_diff < 0 else 0,
+                    credit_in_account_currency=debit_credit_diff if debit_credit_diff > 0 else 0,
+                    voucher_type=gl_map[0].get("voucher_type"),
+                    voucher_no=gl_map[0].get("voucher_no"),
+                    posting_date=gl_map[0].get("posting_date"),
+                    company=company,
+                    remarks="Round-off adjustment",
+                )
+            )
+
+def validate_disabled_accounts(gl_map):
+    """Check that no disabled accounts are used."""
+    db = get_db()
+    for entry in gl_map:
+        account = entry.get("account")
+        if account:
+            disabled = db.get_value("Account", account, "disabled")
+            if disabled:
+                raise InvalidAccountError(
+                    f"Cannot create accounting entries against disabled account: {account}"
+                )
+
+def save_entries(gl_map):
+    """Persist GL entries to the database."""
+    db = get_db()
+    for entry in gl_map:
+        gle = _dict(
+            name=new_name("GLE"),
+            posting_date=entry.get("posting_date"),
+            account=entry.get("account"),
+            party_type=entry.get("party_type"),
+            party=entry.get("party"),
+            cost_center=entry.get("cost_center"),
+            debit=flt(entry.get("debit"), 2),
+            credit=flt(entry.get("credit"), 2),
+            debit_in_account_currency=flt(entry.get("debit_in_account_currency"), 2),
+            credit_in_account_currency=flt(entry.get("credit_in_account_currency"), 2),
+            account_currency=entry.get("account_currency", "USD"),
+            voucher_type=entry.get("voucher_type"),
+            voucher_no=entry.get("voucher_no"),
+            against_voucher_type=entry.get("against_voucher_type"),
+            against_voucher=entry.get("against_voucher"),
+            remarks=entry.get("remarks"),
+            is_opening=entry.get("is_opening", "No"),
+            is_cancelled=0,
+            company=entry.get("company"),
+            fiscal_year=entry.get("fiscal_year"),
+            creation=now(),
+            modified=now(),
+        )
+        db.insert("GL Entry", gle)
+
+def make_reverse_gl_entries(gl_entries=None, voucher_type=None, voucher_no=None):
+    """Create reversing GL entries (swap debit/credit).
+
+    Called on document cancellation.
+    """
+    db = get_db()
+
+    if not gl_entries:
+        gl_entries = db.get_all(
+            "GL Entry",
+            filters={"voucher_type": voucher_type, "voucher_no": voucher_no, "is_cancelled": 0},
+            fields=["*"],
+        )
+
+    if not gl_entries:
+        return
+
+    # Mark original entries as cancelled
+    for entry in gl_entries:
+        db.set_value("GL Entry", entry["name"], "is_cancelled", 1)
+
+    # Create reverse entries
+    for entry in gl_entries:
+        reverse = _dict(
+            name=new_name("GLE"),
+            posting_date=entry.get("posting_date"),
+            account=entry.get("account"),
+            party_type=entry.get("party_type"),
+            party=entry.get("party"),
+            cost_center=entry.get("cost_center"),
+            debit=flt(entry.get("credit"), 2),          # swapped
+            credit=flt(entry.get("debit"), 2),           # swapped
+            debit_in_account_currency=flt(entry.get("credit_in_account_currency"), 2),
+            credit_in_account_currency=flt(entry.get("debit_in_account_currency"), 2),
+            account_currency=entry.get("account_currency", "USD"),
+            voucher_type=entry.get("voucher_type"),
+            voucher_no=entry.get("voucher_no"),
+            against_voucher_type=entry.get("against_voucher_type"),
+            against_voucher=entry.get("against_voucher"),
+            remarks=f"On cancellation of {entry.get('voucher_no')}",
+            is_opening=entry.get("is_opening", "No"),
+            is_cancelled=1,
+            company=entry.get("company"),
+            fiscal_year=entry.get("fiscal_year"),
+            creation=now(),
+            modified=now(),
+        )
+        db.insert("GL Entry", reverse)
+
+    db.commit()
+
+def get_account_balances(account, company=None):
+    """Return (base_balance, account_currency_balance) for an account.
+
+    base_balance sums debit−credit (company currency); account_currency_balance
+    sums the *_in_account_currency columns. For a foreign-currency bank account
+    their ratio is the average carrying rate, used when converting the balance.
+    """
+    db = get_db()
+    query = (
+        'SELECT COALESCE(SUM(debit), 0) - COALESCE(SUM(credit), 0) AS base, '
+        'COALESCE(SUM(debit_in_account_currency), 0) - '
+        'COALESCE(SUM(credit_in_account_currency), 0) AS ccy '
+        'FROM "GL Entry" WHERE account = ? AND is_cancelled = 0'
+    )
+    params = [account]
+    if company:
+        query += " AND company = ?"
+        params.append(company)
+    rows = db.sql(query, params)
+    if not rows:
+        return 0.0, 0.0
+    return flt(rows[0]["base"]), flt(rows[0]["ccy"])
+
+
+def get_gl_balance(account, company=None, posting_date=None):
+    """Get the balance of an account (debit - credit).
+
+    Convenience function for querying account balances.
+    """
+    db = get_db()
+    filters = {"account": account, "is_cancelled": 0}
+    if company:
+        filters["company"] = company
+
+    query = """
+        SELECT
+            COALESCE(SUM(debit), 0) - COALESCE(SUM(credit), 0) as balance
+        FROM "GL Entry"
+        WHERE account = ? AND is_cancelled = 0
+    """
+    params = [account]
+
+    if company:
+        query += " AND company = ?"
+        params.append(company)
+    if posting_date:
+        query += " AND posting_date <= ?"
+        params.append(posting_date)
+
+    result = db.sql(query, params)
+    return flt(result[0]["balance"]) if result else 0