@fuzzle/opencode-accountant 0.0.9 → 0.0.10-next.1

package/README.md

@@ -97,6 +97,7 @@ paths:
   pending: doc/agent/todo/import
   done: doc/agent/done/import
   unrecognized: statements/import/unrecognized
+  rules: ledger/rules
 
 providers:
   revolut:
@@ -115,13 +116,15 @@ providers:
 
   ubs:
     detect:
-      - header: 'Trade date,Trade time,Booking date,Value date,Currency,Debit,Credit,Individual amount,Balance,Transaction no.,Description1,Description2,Description3,Footnotes'
+      # Note: UBS exports have a trailing semicolon in the header row, which creates
+      # an empty field when parsed. The header must include a trailing comma to match.
+      - header: 'Trade date,Trade time,Booking date,Value date,Currency,Debit,Credit,Individual amount,Balance,Transaction no.,Description1,Description2,Description3,Footnotes,'
         currencyField: Currency
         skipRows: 9
         delimiter: ';'
-        renamePattern: 'transactions-ubs-{accountnumber}.csv'
+        renamePattern: 'transactions-ubs-{account-number}.csv'
         metadata:
-          - field: accountnumber
+          - field: account-number
             row: 0
             column: 1
             normalize: spaces-to-dashes
@@ -141,13 +144,14 @@ providers:
 | `pending`      | Base path for classified files awaiting import  |
 | `done`         | Base path for archived files after import       |
 | `unrecognized` | Directory for files that couldn't be classified |
+| `rules`        | Directory containing hledger `.rules` files     |
 
 **Provider Detection Rules:**
 
 | Field             | Required | Description                                                |
 | ----------------- | -------- | ---------------------------------------------------------- |
 | `filenamePattern` | No       | Regex pattern to match against filename                    |
-| `header`          | Yes      | Expected CSV header row (exact match)                      |
+| `header`          | Yes      | Expected CSV header row (comma-separated, exact match)\*   |
 | `currencyField`   | Yes      | Column name containing the currency/symbol                 |
 | `skipRows`        | No       | Number of rows to skip before header (default: 0)          |
 | `delimiter`       | No       | CSV delimiter character (default: `,`)                     |
@@ -155,6 +159,8 @@ providers:
 | `metadata`        | No       | Array of metadata extraction rules (see below)             |
 | `currencies`      | Yes      | Map of raw currency values to normalized folder names      |
 
+\* **Note on trailing delimiters:** If the CSV header row ends with a trailing delimiter (e.g., `Field1;Field2;`), this creates an empty field when parsed. The `header` config must include a trailing comma to account for this (e.g., `Field1,Field2,`).
+
 **Metadata Extraction Rules:**
 
 | Field       | Required | Description                                             |
@@ -171,15 +177,18 @@ your-project/
 ├── config/
 │   └── import/
 │       └── providers.yaml
+├── ledger/
+│   └── rules/                                   # hledger rules files
+│       └── <provider>-{account-number}.rules    # {account-number} from metadata extraction
 ├── statements/
-│   └── import/                  # Drop CSV files here
-│       └── unrecognized/         # Unclassified files moved here
+│   └── import/                                  # Drop CSV files here
+│       └── unrecognized/                        # Unclassified files moved here
 └── doc/
     └── agent/
         ├── todo/
         │   └── import/
-        │       └── <provider>/   # e.g. revolut
-        │           └── <currency>/   # e.g. chf, eur, usd, btc
+        │       └── <provider>/                  # e.g. revolut
+        │           └── <currency>/              # e.g. chf, eur, usd, btc
         └── done/
             └── import/
                 └── <provider>/
@@ -192,7 +201,40 @@ your-project/
 2. Run `classify-statements` tool
 3. Files are moved to `doc/agent/todo/import/<provider>/<currency>/`
 4. Unrecognized files are moved to `statements/import/unrecognized/`
-5. After successful import, files should be moved to `doc/agent/done/import/`
+5. Run `import-statements` with `checkOnly: true` to validate transactions
+6. If unknown postings found: Add rules to the `.rules` file, repeat step 5
+7. Once all transactions match: Run `import-statements` with `checkOnly: false`
+8. Transactions are imported to journal, CSV files moved to `doc/agent/done/import/`
+
+### Statement Import
+
+The `import-statements` tool imports classified CSV statements into hledger using rules files. It validates transactions before import and identifies any that cannot be categorized.
+
+#### Tool Arguments
+
+| Argument    | Type    | Default | Description                                 |
+| ----------- | ------- | ------- | ------------------------------------------- |
+| `provider`  | string  | -       | Filter by provider (e.g., `revolut`, `ubs`) |
+| `currency`  | string  | -       | Filter by currency (e.g., `chf`, `eur`)     |
+| `checkOnly` | boolean | `true`  | If true, only validate without importing    |
+
+#### Rules File Matching
+
+The tool matches CSV files to their rules files by parsing the `source` directive in each `.rules` file. For example, if `ubs-account.rules` contains:
+
+```
+source ../../doc/agent/todo/import/ubs/chf/transactions.csv
+```
+
+The tool will use that rules file when processing `transactions.csv`.
+
+See the hledger documentation for details on rules file format and syntax.
+
+#### Unknown Postings
+
+When a transaction doesn't match any `if` pattern in the rules file, hledger assigns it to `income:unknown` or `expenses:unknown` depending on the transaction direction. The tool reports these so you can add appropriate rules.
+
+For detailed output format examples, see [`docs/tools/import-statements.md`](docs/tools/import-statements.md).
 
 ## Development
 

package/agent/accountant.md

@@ -3,13 +3,13 @@ description: Specialized agent for hledger accounting tasks and transaction mana
 prompt: You are an accounting specialist with expertise in hledger and double-entry bookkeeping. Your role is to help maintain accurate financial records following the user's conventions.
 mode: subagent
 temperature: 0.1
-steps: 5
+steps: 8
 tools:
-  bash: false
+  bash: true
   edit: true
   write: true
 permission:
-  bash: deny
+  bash: allow
   edit: allow
   glob: allow
   grep: allow
@@ -19,30 +19,24 @@ permission:
   todoread: allow
   todowrite: allow
   webfetch: deny
-  write: allow  
+  write: allow
 ---
 
 ## Repository Structure
 
-- `.hledger.journal` - Global hledger journal file,
+- `.hledger.journal` - Global hledger journal file
 - `ledger/` - All ledger related files are stored here
 - `ledger/currencies/` - Currency exchange rate files
 - `ledger/YYYY.journal` - Annual hledger journal files
+- `ledger/rules` - hledger rules files
 - `statements/` - Bank and broker account statements
 - `statements/import` - Upload folder for new statements to process
-- `statements/provider/YYYY` - Location where processed statements are stored
-- `doc/agent/todo/` - Agents task work directory
+- `statements/{provider}/YYYY` - Processed statements organized by source and year
+- `doc/agent/todo/` - Agent's task work directory
 - `doc/agent/done/` - Tasks completed by the agent
 - `config/conventions/` - Accounting conventions
 - `config/rules/` - import rules files
 
-## System Environment
-
-**Required for accounting tasks:**
-
-- `pricehist` - Price data fetching
-- `hledger`, `hledger-fmt` - Accounting operations
-
 ## Conventions & Workflow
 
 All account conventions, conversion patterns (currency, crypto, equity postings), transaction status management, import
@@ -59,15 +53,29 @@ When working with accounting tasks:
 1. **File organization** - Keep transactions in appropriate year journals
 1. **Duplicate checking** - Take extra care to avoid duplicate transactions
 1. **Unintended edits** - If a balance is off, check the journal for unintended edits
-1. **Statement tracking** - Move processed statements to `statements/provider/YYYY`
+1. **Statement tracking** - Move processed statements to `statements/{provider}/YYYY`
+1. **Consistency** - Maintain consistent formatting and naming conventions across all files
+
+## Statement Import Workflow
+
+Use the `import-statements` tool to import bank statements. The workflow:
 
-## Common Tasks
+1. **Prepare**: Drop CSV files into `statements/import/`
+2. **Classify**: Run `classify-statements` tool to move files to `doc/agent/todo/import/<provider>/<currency>/`
+3. **Validate (check mode)**: Run `import-statements(checkOnly: true)` to validate transactions
+   - Tool runs `hledger print` dry run to check for unknown postings
+   - Unknown postings appear as `income:unknown` or `expenses:unknown`
+4. **Handle unknowns**: If unknown postings found:
+   - Tool returns full CSV row data for each unknown posting
+   - Analyze the CSV row data to understand the transaction
+   - Create or update rules file with `if` directives to match the transaction
+   - Repeat step 3 until all postings are matched
+5. **Import**: Once all transactions have matching rules, run `import-statements(checkOnly: false)`
+6. **Complete**: Transactions imported to journal, CSVs moved to `doc/agent/done/import/`
 
-- Adding new transactions from statements
-- Processing crypto purchases and transfers
-- Currency conversions between CHF/EUR/USD
-- Validating journal integrity
-- Generating balance reports
-- Correcting malformed transactions
+### Rules Files
 
-Focus on accuracy, precision, and strict adherence to the repository's accounting conventions.
+- Rules files are in `config/rules/` directory
+- Match CSV to rules file via the `source` directive in each `.rules` file
+- Use field names from the `fields` directive for matching
+- Unknown account pattern: `income:unknown` (positive amounts) / `expenses:unknown` (negative amounts)