teri 0.5.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dfc371293c931614edbc46daf5d3e25c19b4d7d4199a0119c6b8d6db3a6da8df
+  data.tar.gz: 1042ecd7e4c4ed6a0f0966311ada34fb81c341f6d3f80ef66f06fc7b39d530f0
+SHA512:
+  metadata.gz: acd83189eed624a8e04f387873cf73650dae5a9eb68faeb97d2baff708974027cd6fcc1e200c5e2d3fbb9d21144982e0791c358274f31f97ca5d3df6c6f2085f
+  data.tar.gz: b7c4ca31d5b59e8e83612c2f0ca9578c9f52da017e07cc6856b821179fdbcdcb32aba59415e150d9b572fbdd8138edccff43209808fa005ba4f4e97b6929fed8

data/LICENSE.txt

@@ -0,0 +1,25 @@
+PROPRIETARY LICENSE
+
+Copyright (c) 2025 Jonathan Siegel. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are the proprietary and confidential property of Jonathan Siegel. The Software is protected by copyright laws and international treaty provisions.
+
+Unauthorized reproduction, distribution, modification, or use of this Software, in whole or in part, is strictly prohibited without the express written permission of Jonathan Siegel.
+
+LIMITED LICENSE:
+Subject to the terms and conditions of this License, Jonathan Siegel grants you a non-transferable, non-exclusive, limited license to use the Software solely for your personal or internal business purposes. You may not:
+
+1. Modify, adapt, alter, translate, or create derivative works of the Software;
+2. Reverse engineer, decompile, disassemble, or attempt to derive the source code of the Software;
+3. Rent, lease, loan, sell, sublicense, distribute, transmit, or otherwise transfer rights to the Software;
+4. Remove or alter any proprietary notices, labels, or marks on the Software;
+5. Use the Software for commercial purposes without a separate written agreement.
+
+TERMINATION:
+This License is effective until terminated. Your rights under this License will terminate automatically without notice if you fail to comply with any of its terms and conditions.
+
+NO WARRANTY:
+THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. JONATHAN SIEGEL DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+LIMITATION OF LIABILITY:
+IN NO EVENT SHALL JONATHAN SIEGEL BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE SOFTWARE. 

data/README.md

@@ -0,0 +1,285 @@
+# Teri
+
+Teri is a double-entry accounting tool for personal banking. It helps manage banking transactions in ledger format, allowing you to code transactions, generate balance sheets, and income statements.
+
+## Understanding Debits and Credits in Double-Entry Accounting
+
+In double-entry accounting, every transaction is recorded in two accounts: one with a **debit (Dr.)** and one with a **credit (Cr.)**. Debits and credits reflect opposite sides of a transaction, ensuring every transaction stays balanced.
+
+### Definitions:
+
+- **Debit (Dr.)**: Represents the **left side** of an accounting entry.
+- **Credit (Cr.)**: Represents the **right side** of an accounting entry.
+
+**Important:**  
+**Debits must always equal credits** for every transaction.
+
+---
+
+### Impact of Debits and Credits by Account Type:
+
+| Account Type         | Debit (Dr.)             | Credit (Cr.)            |
+|----------------------|-------------------------|-------------------------|
+| **Assets**           | **Increase ⬆️**         | Decrease ⬇️             |
+| **Liabilities**      | Decrease ⬇️             | **Increase ⬆️**         |
+| **Equity**           | Decrease ⬇️             | **Increase ⬆️**         |
+| **Income (Revenue)** | Decrease ⬇️             | **Increase ⬆️**         |
+| **Expenses**         | **Increase ⬆️**         | Decrease ⬇️             |
+
+**Mnemonic** (to remember easily): **DEALER**
+
+- **D**ividends, **E**xpenses, **A**ssets increase with **Debit**
+- **L**iabilities, **E**quity, **R**evenue increase with **Credit**
+
+---
+
+### Example Scenario:
+
+1. **Invest $50,000 cash into your company**:
+    - **Debit**: `Assets:Cash` **$50,000** (Cash increases)
+    - **Credit**: `Equity:Owner's Capital` **$50,000** (Equity increases)
+
+2. **Buy property for $35,000**:
+    - **Debit**: `Assets:Property` **$35,000** (Property increases)
+    - **Credit**: `Assets:Cash` **$35,000** (Cash decreases)
+
+3. **Pay $1,500 for property maintenance**:
+    - **Debit**: `Expenses:Maintenance` **$1,500** (Expenses increase)
+    - **Credit**: `Assets:Cash` **$1,500** (Cash decreases)
+
+4. **Receive $2,000 rental income**:
+    - **Debit**: `Assets:Cash` **$2,000** (Cash increases)
+    - **Credit**: `Income:Rental Income` **$2,000** (Revenue increases)
+
+---
+
+### Why Use Debits and Credits?
+
+Debits and credits enforce the core accounting equation:
+
+\[
+\text{Assets} = \text{Liabilities} + \text{Equity}
+\]
+
+This ensures financial statements remain balanced, accurate, and easy to verify.
+
+---
+
+### Quick Summary:
+
+- **Debit (Dr.) = Left side**: Increases Assets, Expenses; Decreases Liabilities, Equity, Income
+- **Credit (Cr.) = Right side**: Increases Liabilities, Equity, Income; Decreases Assets, Expenses
+
+Each accounting entry must balance with equal **debits and credits**.
+
+## Ledger
+
+```
+$ ledger -f current.ledger bal ^Income ^Expenses --invert
+      -13,166.68 USD  Expenses:Maintenance
+$ ledger -f current.ledger bal Assets Liabilities Equity
+        1,833.32 USD  Assets:Mercury Checking ••1090
+      -15,000.00 USD  Equity:Capital
+--------------------
+      -13,166.68 USD
+```
+
+### Consistent Currency Formatting
+
+To ensure all amounts are displayed with the same currency format (using $ symbol), use the `--exchange $` option:
+
+```
+$ ledger -f current.ledger --exchange $ bal Assets Liabilities Equity
+          $1,833.32  Assets:Mercury Checking ••1090
+        $-15,000.00  Equity:Capital
+--------------------
+        $-13,166.68
+```
+
+This option converts all currencies to dollars and displays them with the $ symbol, preventing mixed currency formats in the output.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'teri'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install teri
+```
+
+## Usage
+
+Teri provides several commands to help you manage your banking transactions:
+
+### Code Transactions
+
+```bash
+# Code new transactions
+teri code
+
+# Code transactions using a reconciliation file
+teri code -f reconcile_example.txt
+
+# Code transactions using saved responses
+teri code -r responses.txt
+
+# Code transactions and save responses
+teri code -s new_responses.txt
+
+# Code transactions with OpenAI suggestions
+# (requires OPENAI_API_KEY environment variable or -k option)
+teri code
+
+# Code transactions with a specific OpenAI API key
+teri code -k your_api_key_here
+
+# Code transactions without OpenAI suggestions
+teri code -d
+
+# Code transactions with auto-apply for OpenAI suggestions
+teri code -a
+```
+
+### AI-Assisted Transaction Coding
+
+Teri can use OpenAI's API to suggest categories for transactions based on their details and previous codings. This feature helps streamline the coding process by providing intelligent suggestions.
+
+#### How It Works
+
+1. When coding a transaction, Teri sends the transaction details (description, amount, counterparty, etc.) to OpenAI's API.
+2. OpenAI analyzes the transaction and suggests the most appropriate category based on the available categories and previous codings.
+3. The suggestion is displayed to the user, who can choose to accept it or select a different category.
+4. The user can also select option 'A' to automatically apply OpenAI's suggestions for all remaining transactions in the session.
+
+#### Requirements
+
+- An OpenAI API key (set as the `OPENAI_API_KEY` environment variable or provided with the `-k` option)
+- The `ruby-openai` gem (included as a dependency)
+
+#### Configuration Options
+
+- `-k, --openai-api-key`: Specify the OpenAI API key (defaults to the `OPENAI_API_KEY` environment variable)
+- `-d, --disable-ai`: Disable AI suggestions
+- `-a, --auto-apply-ai`: Automatically apply AI suggestions for all transactions
+
+#### Logging
+
+Teri automatically logs all interactions with OpenAI and user inputs during coding sessions. This helps with:
+
+- Debugging issues with AI suggestions
+- Tracking the prompts sent to OpenAI
+- Reviewing user decisions and feedback
+- Auditing transaction categorization decisions
+
+Log files are stored in the `logs` directory with timestamps in their filenames:
+- `logs/coding_session_YYYYMMDD_HHMMSS.log`: Contains logs of the coding session, including user interactions and decisions
+- `logs/openai_YYYYMMDD_HHMMSS.log`: Contains the detailed prompts sent to OpenAI and the responses received
+
+The logs include:
+- Transaction details
+- AI suggestions and confidence levels
+- User selections and feedback
+- Categorization decisions
+
+This logging system helps maintain a record of all transaction coding decisions and the AI's role in those decisions, which can be valuable for auditing and improving the system over time.
+
+### Check Uncoded Transactions
+
+```bash
+# Check for uncoded transactions
+teri check-uncoded
+```
+
+### Generate Reports
+
+```bash
+# Generate balance sheet for the last 2 years
+teri balance-sheet
+
+# Generate balance sheet for the last 5 years
+teri balance-sheet -p 5
+
+# Generate income statement for the last 2 years
+teri income-statement
+
+# Generate income statement for the last 5 years
+teri income-statement -p 5
+```
+
+### Close Year
+
+```bash
+# Close the books for the previous year
+teri close-year
+
+# Close the books for a specific year
+teri close-year -y 2021
+```
+
+### Fix Balance Sheet
+
+```bash
+# Fix the balance sheet
+teri fix-balance
+```
+
+### Version Information
+
+```bash
+# Display version information
+teri version
+```
+
+## File Structure
+
+- `transactions/*.ledger`: Original transaction files
+- `coding.ledger`: Contains reverse transactions for proper categorization
+
+## Reconciliation File Format
+
+You can use a reconciliation file to batch process transactions instead of coding them interactively. The file format is:
+
+```
+transaction_id,category1:amount1,category2:amount2,...
+```
+
+- If amount is not specified, the full transaction amount will be used
+- For split transactions, specify multiple categories with their respective amounts
+- Lines starting with # are treated as comments
+
+Example:
+```
+# Single category coding
+0ac547b2-8d8e-11eb-870c-ef6812d46c47,Expenses:Rent
+
+# Split transaction
+dbd348b4-8d88-11eb-8f51-5f5908fef419,Income:Sales:10000.00,Income:Services:5000.00
+
+# Loan payment split between principal and interest
+46fa4d2e-be4c-11eb-a705-afde9e1ac01b,Expenses:Loan:Principal:150.00,Expenses:Interest:28.00
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/example/teri.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT). 

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "teri"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__) 

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here 

data/bin/teri

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'teri'
+
+Teri::CLI.start(ARGV) 

data/lib/teri/accounting.rb

@@ -0,0 +1,310 @@
+require 'English'
+require 'date'
+require 'fileutils'
+require 'securerandom'
+require 'logger'
+require_relative 'openai_client'
+require_relative 'category_manager'
+require_relative 'transaction_coder'
+require_relative 'report_generator'
+require_relative 'ai_integration'
+
+module Teri
+  # IO adapter for handling input/output operations
+  # This allows for better testing by injecting a test adapter
+  class IOAdapter
+    def puts(message)
+      Kernel.puts message
+    end
+
+    def print(message)
+      Kernel.print message
+    end
+
+    def gets
+      $stdin.gets
+    end
+  end
+
+  # File adapter for handling file operations
+  # This allows for better testing by injecting a test adapter
+  class FileAdapter
+    def exist?(path)
+      File.exist?(path)
+    end
+
+    def read(path)
+      File.read(path)
+    end
+
+    def readlines(path)
+      File.readlines(path)
+    end
+
+    def open(path, mode, &)
+      File.open(path, mode, &)
+    end
+
+    def warning(message)
+      puts "Warning: #{message}"
+    end
+  end
+
+  class Accounting
+    attr_reader :transactions, :coded_transactions, :options, :logger, :previous_codings, :counterparty_hints
+
+    def initialize(options = {})
+      @transactions = []
+      @coded_transactions = {}
+      
+      # Convert string keys to symbol keys
+      symbolized_options = {}
+      options.each do |key, value|
+        symbolized_options[key.to_sym] = value
+      end
+      
+      @options = {
+        year: Date.today.year,
+        month: nil,
+        periods: 2, # Default to 2 previous periods
+        response_file: nil, # Add option for response file
+        save_responses_file: nil, # Add option for saving responses
+        adjustment_asset_account: nil, # Add option for adjustment asset account
+        adjustment_equity_account: nil, # Add option for adjustment equity account
+        openai_api_key: ENV.fetch('OPENAI_API_KEY', nil), # Add option for OpenAI API key
+        use_ai_suggestions: true, # Add option to enable/disable AI suggestions
+        auto_apply_ai: false, # Add option to auto-apply AI suggestions
+        log_file: nil,
+      }.merge(symbolized_options)
+      
+      # Set up logging
+      setup_logger
+
+      # Initialize IO and File adapters
+      @io = IOAdapter.new
+      @file = FileAdapter.new
+
+      # Initialize category manager
+      @category_manager = CategoryManager.new
+
+      # Initialize AI integration
+      @ai_integration = AIIntegration.new(@options, @logger, @log_file)
+      @openai_client = @ai_integration.openai_client
+
+      # Initialize transaction coder
+      @transaction_coder = TransactionCoder.new(@category_manager, @ai_integration, @options, @logger)
+
+      # Initialize report generator
+      @report_generator = ReportGenerator.new(@options, @logger)
+
+      # Initialize previous codings cache
+      @previous_codings = {}
+      @counterparty_hints = {}
+
+      # Load previous codings if we have an OpenAI client and a file
+      load_previous_codings(@file) if @openai_client && @file
+    end
+
+    # Set up the logger
+    def setup_logger
+      # Skip logger setup if we're in a test environment
+      if defined?(RSpec)
+        @logger = nil
+        return
+      end
+
+      begin
+        # Create logs directory if it doesn't exist
+        FileUtils.mkdir_p('logs')
+
+        # Create a log file with timestamp
+        @log_file = "logs/coding_session_#{Time.now.strftime('%Y%m%d_%H%M%S')}.log"
+
+        @logger = Logger.new(@log_file)
+        @logger.level = Logger::INFO
+        @logger.formatter = proc do |severity, datetime, _progname, msg|
+          "#{datetime.strftime('%Y-%m-%d %H:%M:%S')} [#{severity}] #{msg}\n"
+        end
+
+        @logger.info('Coding session started')
+        @logger.info("Options: #{@options.inspect}")
+      rescue StandardError => e
+        puts "Warning: Failed to set up logging: #{e.message}"
+        @logger = nil
+      end
+    end
+
+    def load_transactions(filelist: Dir.glob('transactions/*.ledger'))
+      # Clear existing transactions
+      @transactions = []
+      
+      # Load all transactions from ledger files
+      filelist.each do |file|
+        ledger = Ledger.parse(file)
+        file_transactions = ledger.transactions.map { |hash| Transaction.from_ledger_hash(hash) }
+        @transactions.concat(file_transactions)
+      end
+    end
+
+    def load_coded_transactions
+      # Initialize the coded transactions hash
+      @coded_transactions = {}
+      
+      # Check if coding.ledger exists
+      return unless File.exist?('coding.ledger')
+      
+      # Use Ledger.parse to read the coding.ledger file
+      Ledger.parse('coding.ledger').transactions.each do |transaction|
+        @coded_transactions[transaction[:transaction_id]] = true
+      end
+
+      # Also check for transaction IDs directly in the file content
+      # This is a fallback in case the Ledger.parse method doesn't capture all transaction IDs
+      begin
+        coding_ledger_content = File.read('coding.ledger')
+        # Look for transaction IDs in comments (e.g., "; Original Transaction ID: 1234-5678")
+        coding_ledger_content.scan(/;\s*(?:Original\s+)?Transaction\s+ID:?\s*([a-zA-Z0-9-]+)/).each do |match|
+          @coded_transactions[match[0]] = true
+        end
+
+        # Also look for transaction IDs in the transaction headers
+        # Format: YYYY-MM-DD * Transaction Description ; Transaction ID: 1234-5678
+        coding_ledger_content.scan(/\d{4}-\d{2}-\d{2}.*?;\s*(?:Transaction\s+ID:?\s*|ID:?\s*)([a-zA-Z0-9-]+)/).each do |match|
+          @coded_transactions[match[0]] = true
+        end
+      rescue StandardError => e
+        @logger&.error("Error reading coding.ledger file: #{e.message}")
+        puts "Warning: Error reading coding.ledger file: #{e.message}"
+      end
+
+      @logger&.info("Loaded #{@coded_transactions.size} coded transactions")
+      @coded_transactions
+    end
+
+    def code_transactions
+      load_transactions
+
+      # Get uncoded transactions
+      uncoded_transactions = @transactions.select do |transaction|
+        transaction.entries.any? { |entry| entry.account.include?('Unknown') }
+      end
+
+      if uncoded_transactions.empty?
+        puts 'No uncoded transactions found.'
+        return
+      end
+
+      # Check if we should use a reconciliation file
+      return process_reconcile_file(uncoded_transactions) if @options[:reconcile_file]
+
+      # Initialize variables for responses
+      responses = nil
+        saved_responses = nil
+        
+      # Check if we should use saved responses
+      if @options[:responses_file]
+        if File.exist?(@options[:responses_file])
+          @logger&.info("Using responses from file: #{@options[:responses_file]}")
+          puts "Using responses from file: #{@options[:responses_file]}"
+          responses = File.readlines(@options[:responses_file]).map(&:strip)
+        else
+          @logger&.error("Responses file not found: #{@options[:responses_file]}")
+          puts "Error: Responses file not found: #{@options[:responses_file]}"
+          return
+        end
+      end
+      
+      # Check if we should save responses
+      if @options[:save_responses_file]
+        @logger&.info("Saving responses to file: #{@options[:save_responses_file]}")
+        puts "Saving responses to file: #{@options[:save_responses_file]}"
+        saved_responses = []
+      end
+
+      # Load previous codings for AI suggestions
+      load_previous_codings(@file) if @openai_client
+
+      # Code each transaction
+      uncoded_transactions.each do |transaction|
+        @logger&.info("Coding transaction: #{transaction.transaction_id} - #{transaction.description}")
+
+        # Code the transaction interactively
+        result = @transaction_coder.code_transaction_interactively(
+          transaction, 
+          responses, 
+          saved_responses, 
+          @options[:auto_apply_ai],
+          @io
+        )
+
+        # Check if the user wants to auto-apply AI suggestions
+        if result == 'A'
+          @logger&.info('User selected auto-apply AI suggestions')
+          @options[:auto_apply_ai] = true
+        end
+      end
+      
+      # Save responses if requested
+      return unless @options[:save_responses_file] && saved_responses
+
+      @logger&.info("Writing #{saved_responses.size} responses to file: #{@options[:save_responses_file]}")
+      File.write(@options[:save_responses_file], saved_responses.join("\n"))
+      puts "Responses saved to: #{@options[:save_responses_file]}"
+    end
+
+    def process_reconcile_file(uncoded_transactions)
+      @transaction_coder.process_reconcile_file(uncoded_transactions, @options[:reconcile_file])
+    end
+
+    def check_uncoded_transactions
+      # Load transactions from ledger files
+      load_transactions
+      
+      # Load previously coded transactions
+      load_coded_transactions
+      
+      # Find uncoded transactions
+      @transactions.reject { |t| @coded_transactions[t.transaction_id] }
+    end
+
+    def generate_balance_sheet(options = {})
+      @report_generator.generate_balance_sheet(options)
+    end
+
+    def generate_income_statement(options = {})
+      @report_generator.generate_income_statement(options)
+    end
+
+    def all_categories
+      @category_manager.all_categories
+    end
+
+    # Load previous codings from coding.ledger for AI suggestions
+    def load_previous_codings(file_adapter = @file)
+      # Delegate to AI integration
+      @ai_integration.load_previous_codings(file_adapter)
+      
+      # Update our local references to the data
+      @previous_codings = @ai_integration.previous_codings
+      @counterparty_hints = @ai_integration.counterparty_hints
+    end
+
+    # Expose previous codings for OpenAI client
+    def previous_codings
+      @previous_codings
+    end
+
+    # Expose counterparty hints for OpenAI client
+    def counterparty_hints
+      @counterparty_hints
+    end
+
+    def code_transaction(transaction, selected_option, split_input = nil, new_category = nil)
+      @transaction_coder.code_transaction(transaction, selected_option, split_input, new_category)
+    end
+
+    def code_transaction_interactively(transaction, responses = nil, saved_responses = nil, auto_apply_ai = false, io = @io)
+      @transaction_coder.code_transaction_interactively(transaction, responses, saved_responses, auto_apply_ai, io)
+    end
+  end
+end