mirror of
https://github.com/we-promise/sure.git
synced 2026-08-05 00:22:17 +00:00
ec38a89d0c
A user wants to manage patrimonial history — a document-backed record of a family's wealth where every figure traces back to the statement it came from — by pointing an external agent harness at Sure. That model belongs in the harness, not in Sure: it needs numbered build deltas, golden tests and closed periods that a mutable Postgres row cannot provide. What Sure was missing was the seam. The Statement Vault already does most of the work — original bytes retained, SHA-256 dedup, period detection, account matching with a confidence score, reconciliation against ledger balances, and a month-by-month coverage map — but it is reachable only from the web UI. An agent could not archive a document, cite one, or check for gaps. Adds five preview MCP tools over what already exists, plus a citation grammar for values the agent writes: - upload_account_statement, list_account_statements, get_account_statement, get_statement_coverage - record_valuation, whose source citation is parsed rather than trusted: ["estimated: "] citation [" (grade: A|B|C)"]. An uncited or free-styled value is rejected at the write boundary instead of landing in the ledger looking authoritative. link and reject are deliberately not exposed. Attaching a statement to an account is the human's decision, and the vault UI is where it is made; the agent reports the suggested match and stops there. Assistant.function_classes now takes a user so preview tools stay out of the default surface. They are hidden from tools/list and not callable by name without the preference enabled, and the vault tools re-check the manager role and per-account permissions, since MCP calls never pass through a controller. Docs: the blueprint this implements, and a guide covering which side owns which layer, the vocabulary map between the two, the monthly runbook, and the gaps (non-user holders, non-statement documents, one value per date). No migrations, no API endpoints, no UI. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JFDp9HhXDeswadu4cxFojn
105 lines
3.2 KiB
Ruby
105 lines
3.2 KiB
Ruby
# frozen_string_literal: true
|
|
|
|
class Assistant::Function::GetAccountStatement < Assistant::Function
|
|
include Assistant::Function::StatementVaultSupport
|
|
|
|
DOWNLOAD_URL_TTL = 15.minutes
|
|
|
|
class << self
|
|
def name
|
|
"get_account_statement"
|
|
end
|
|
|
|
def description
|
|
<<~INSTRUCTIONS
|
|
Fetch one Statement Vault document by ID: its identity (SHA-256, filename,
|
|
period), the balances read off the document, and the reconciliation checks
|
|
comparing those balances against the ledger.
|
|
|
|
The reconciliation checks are the trustworthy part. Each compares a figure
|
|
printed on the statement against the account's recorded balance:
|
|
|
|
- `opening_balance` / `closing_balance` — the statement's figure vs the ledger's
|
|
- `period_movement` — the change across the period, both sides
|
|
|
|
Each check reports `matched` or `mismatched` (tolerance: 0.01). A mismatch
|
|
means the ledger and the document disagree — report it, and do not paper
|
|
over it by adjusting the number to fit.
|
|
|
|
Also returns a short-lived download URL (valid #{DOWNLOAD_URL_TTL.inspect})
|
|
for the original file when one is attached.
|
|
|
|
Example:
|
|
|
|
```
|
|
get_account_statement({ statement_id: "abc123-def456" })
|
|
```
|
|
INSTRUCTIONS
|
|
end
|
|
end
|
|
|
|
def strict_mode?
|
|
false
|
|
end
|
|
|
|
def params_schema
|
|
build_schema(
|
|
required: [ "statement_id" ],
|
|
properties: {
|
|
statement_id: {
|
|
type: "string",
|
|
description: "UUID of the statement, as returned by list_account_statements or upload_account_statement."
|
|
}
|
|
}
|
|
)
|
|
end
|
|
|
|
def call(params = {})
|
|
return not_a_statement_manager unless statement_manager?
|
|
|
|
statement = find_statement(params["statement_id"])
|
|
|
|
unless statement&.viewable_by?(user)
|
|
return error("not_found", "No statement found with that ID that this user can view.")
|
|
end
|
|
|
|
{
|
|
success: true,
|
|
statement: statement_payload(statement).merge(
|
|
reconciliation_status: statement.reconciliation_status,
|
|
reconciliation_checks: reconciliation_payload(statement),
|
|
download_url: download_url(statement)
|
|
).compact
|
|
}
|
|
end
|
|
|
|
private
|
|
def reconciliation_payload(statement)
|
|
statement.reconciliation_checks.map do |check|
|
|
{
|
|
check: check[:key],
|
|
statement_amount: check[:statement_amount].to_s,
|
|
ledger_amount: check[:ledger_amount].to_s,
|
|
difference: check[:difference].to_s,
|
|
status: check[:status]
|
|
}
|
|
end
|
|
end
|
|
|
|
# Chat and MCP clients render outside the request that produced the record, so
|
|
# the URL has to be absolute. Falls back to nil when no host is configured
|
|
# (e.g. a self-hosted worker with no APP_DOMAIN) rather than handing back a
|
|
# relative path an external agent cannot resolve.
|
|
def download_url(statement)
|
|
return nil unless statement.original_file.attached?
|
|
|
|
host_opts = Rails.application.config.action_mailer.default_url_options || {}
|
|
return nil if host_opts[:host].blank?
|
|
|
|
Rails.application.routes.url_helpers.rails_blob_url(
|
|
statement.original_file,
|
|
host_opts.merge(disposition: "attachment", expires_in: DOWNLOAD_URL_TTL)
|
|
)
|
|
end
|
|
end
|