grandice Financial agents
GRANDICE DOMAIN INTELLIGENCE
TECHNICAL WHITE PAPER · VERSION 1.0

Financial Analysis Agents

Deterministic, source-attributed decision support with bounded authority and review-gated outputs.

An implementation-oriented architecture for portfolio concentration, bounded risk assessment, and historical company financial analysis.

CALCULATEDISCLOSEREVIEW
PublishedSeptember 2026
Methodologygrandice-domain-1.0.0
StatusInitial implementation
00

ABSTRACT

Controlled financial analysis—not autonomous financial advice.

Grandice provides three constrained financial-analysis agents for portfolio concentration, bounded risk assessment, and historical company-ratio analysis. Each agent dispatches a strict, typed request to predefined deterministic calculations.

Inputs include caller-provided source metadata and effective dates. Outputs include methodology version, source citations, assumptions, limitations, warnings, and an invariant requirement for professional review. The architecture deliberately excludes open-ended objectives, web browsing, live market-data retrieval, order execution, account modification, and model-generated tool arguments.

Grandice Privacy Shield can protect data locally in the client SDK or sidecar before transfer, and the gateway applies a second residual policy scan before financial schema validation. Detected categories are rejected before calculation, while domain audit records retain operational metadata without request or response bodies.

01

EXECUTIVE PERSPECTIVE

Standardize repeatable analysis without hiding the decision boundary.

Financial teams frequently inherit calculations spread across spreadsheets, scripts, and analyst-specific conventions. Source dates become detached from outputs, formula changes are difficult to trace, and generative systems can add nondeterministic interpretation where repeatability matters.

01

Formula drift

Thresholds and denominator rules diverge between teams and versions.

02

Detached provenance

Results circulate without the source identifier or effective date that supported them.

03

Excessive authority

Broad agent permissions conflict with least-authority controls in regulated workflows.

04

Content-heavy audit

Logging full requests can create a second repository of confidential financial data.

Grandice addresses the calculation and control-plane portion of this problem. It converts caller-supplied, dated facts into reproducible analytical outputs under declared schemas and methodology versions. The consuming institution remains responsible for source quality, validation, supervision, suitability, communications, and any resulting action.

02

SCOPE AND RESPONSIBILITY BOUNDARY

Layered privacy and bounded financial authority.

“Financial Advisor Agent” is used as an umbrella product term for a constrained analysis suite and developer control plane. Financial judgment, suitability, compliance approval, and any resulting action remain with qualified professionals and the adopting institution’s governed processes.

Implemented

  • Exact-decimal portfolio arithmetic
  • Transparent bounded risk scoring
  • Historical company-ratio calculations
  • Caller-attributed source metadata
  • Local SDK or sidecar protection before transfer
  • Gateway residual scanning before financial validation
  • Body-free domain audit metadata
  • Mandatory professional-review flag

Outside current authority

  • Personalized buy, sell, hold, product, or allocation advice
  • Suitability, fiduciary, or regulatory-compliance determinations
  • Live market data, browsing, forecasts, or source verification
  • Order routing, trading, rebalancing, or account modification
  • Model-generated tool calls or unrestricted agent objectives
  • Automatic approval or downstream action without professional review
03

DESIGN PRINCIPLES

Six controls shape the system.

01

Deterministic financial arithmetic

Identical valid inputs and methodology versions produce identical calculation outputs.

02

Bounded agent authority

Each registered agent accepts one declared schema and invokes only predefined calculations.

03

Source-attributed inputs

Fact-bearing records reference caller-provided source identifiers and explicit as-of dates.

04

Data minimization

Identity fields, unrestricted objectives, and free-form personal profiles are excluded from financial schemas.

05

Metadata-oriented auditability

Receipts retain execution facts while excluding financial request and response bodies.

06

Mandatory professional review

Every analysis response carries professional_review_required: true.

04

SYSTEM ARCHITECTURE

A fail-closed request path for configured controls.

The gateway authenticates and bounds the request before financial validation. Raw JSON is inspected for configured sensitive-data patterns, then validated against a strict domain schema. Only validated inputs reach the deterministic calculation layer.

Controlled financial analysis request lifecycle A request flows through authentication, resource bounds, privacy scan, validation, deterministic workflow, disclosure assembly, audit metadata, and professional review. Detection and validation failures are rejected before calculation. GRANDICE CONTROLLED EXECUTION BOUNDARY Institution applicationAPI key · JSON request · privacy mode Authentication + quotaKey, member and organization controls Body + structure bounds2 MiB · 14 levels · 25,000 values Privacy residual scanBest-effort configured pattern coverage Reject before calculationDetected category · HTTP 422 Strict typed validationExact decimals · sources · extra fields denied Sanitized errorInvalid values are not echoed Deterministic workflowMetrics · flags · disclosures Body-free audit metadataRun facts only · no analysis payload Professional reviewInstitution-owned downstream decision
Figure 1. Controlled analysis lifecycle. No browsing, live feed, model-generated tool arguments, or trade execution occurs within the boundary.
05

MANAGED-AGENT RUNTIME

One declared schema maps to one deterministic workflow.

In this release, “agent” means a registered typed workflow—not an open-ended planner. Tool names in the registry describe fixed calculation capabilities. They do not represent model-selectable external actions.

Three-agent authority boundary PERMITTED AUTHORITY: DECLARED SCHEMA → PREDEFINED DETERMINISTIC TOOLS Managed-agent registryVersioned IDs · policy · schema · analyzer Portfolio analystfinancial.portfolio-analyst.v1Decimal portfolio mathAllocation aggregationConcentration rules Risk assessmentfinancial.risk-assessment.v1Weighted risk scoreBounded dimensionsRisk-band rules Company analystfinancial.company-analyst.v1Statement ratiosHistorical growthValuation arithmetic Common disclosure envelopeSources · assumptions · warnings · review OUTSIDE AUTHORITYunrestricted objectivesweb + market feedsaccount accessorders + tradestool generation
Figure 2. Agent authority is bounded by code and schema. The common envelope does not convert screening results into approved recommendations.
PORTFOLIO

Portfolio Analysis Agent

financial.portfolio-analyst.v1

Calculates weights, allocation by asset class, sector and country, top concentration, HHI, effective positions, and transparent diversification flags.

Excludes correlation, volatility, liquidity, tax, fees, transaction costs, look-through exposure, and allocation recommendations.

RISK

Risk Assessment Agent

financial.risk-assessment.v1

Applies disclosed fixed weights to five caller-scored dimensions bounded from one through five, then maps the score to a transparent band.

Not a psychometric instrument, suitability determination, or product-selection mechanism.

COMPANY

Company Financial Analysis Agent

financial.company-analyst.v1

Calculates historical growth, margins, net debt, leverage, and supported valuation multiples from two or more cited financial periods.

Excludes forecasts, peer normalization, DCF, accounting adjustments, and valuation opinions.

06

METHODOLOGY

Inspectable formulas replace opaque model arithmetic.

6.1

Portfolio concentration and allocation

For each position i, market value Vi is divided by the total portfolio market value. Category allocations aggregate values before division.

Total market valueVtotal = Σ Vi
Position weightwi = Vi / Vtotal
Category weightwc = Σi∈c Vi / Vtotal
Herfindahl–Hirschman IndexHHI = Σ wi2
Effective positionsNeffective = 1 / HHI

Effective positions express concentration equivalence, not economic diversification. Ten holdings do not imply ten effective positions when value is concentrated in a smaller subset.

< 5positions
> 25%single position
> 0.18HHI
> 80%single asset class

Current screening thresholds use unrounded values. Rounded output is presentation only. Triggered rules are indicators—not instructions to rebalance.

6.2

Bounded risk scoring

Each caller-scored rating rj is an integer from one to five. Ratings are normalized to a zero-to-one-hundred scale and combined with fixed disclosed weights.

Normalized componentnj = ((rj − 1) / 4) × 100
Aggregate scoreS = Σ αj nj
Loss tolerance30%
Time horizon25%
Financial stability20%
Liquidity flexibility15%
Investment knowledge10%
LOWER0 ≤ S < 40
MODERATE40 ≤ S < 70
HIGHER70 ≤ S ≤ 100

Weights and bands are transparent policy choices. Transparency alone does not establish empirical validity or suitability for a population.

6.3

Company financial analysis

Historical growth(Current − Prior) / |Prior|Omitted when the prior value is zero
MarginProfit measure / RevenueGross, operating, net, and EBITDA where supplied
Net debtTotal debt − CashNet-debt-to-EBITDA only when EBITDA is positive
Market capitalizationDiluted shares × Share priceRequires both latest-period inputs
Enterprise valueMarket cap + Total debt − CashPoint-in-time arithmetic
Valuation multiplesP/S · P/E · EV/EBITDAReported only when denominators support them
07

PROVENANCE STRUCTURE

Source attribution is validated; source truth is not inferred.

Each analysis carries an analysis date and one or more source records. Fact-bearing positions, risk profiles, and financial periods reference a declared opaque source identifier.

Source grounding and temporal integrity graph Analysis as_ofEffective boundary date SOURCE S1opaque ID · citation · as_ofcaller-supplied SOURCE S2opaque ID · citation · as_ofcaller-supplied SOURCE Snopaque ID · citation · as_ofcaller-supplied Position / profilesource_id resolves to S1 Financial periodsource_id resolves to S2 Additional recordsource_id resolves to Sn
Figure 3. Unique and resolvable references plus temporal consistency are enforced. Grandice does not authenticate a publication, verify its contents, or determine economic comparability.
Unique source IDsResolvable referencesSource date ≤ analysis datePeriod date ≤ source date
08

PRIVACY AND DATA MINIMIZATION

Layer controls, then describe their limits precisely.

The strongest workflow protects sensitive values locally in the client SDK or loopback sidecar. The domain gateway still performs a residual pattern scan over raw JSON before schema validation. Detected categories cause rejection rather than mutation of typed financial inputs.

Privacy defense in depth RISK REDUCTION — NOT A GUARANTEE OF COMPLETE SENSITIVE-DATA DETECTION 01MinimizeOpaque identifiersBounded fields 02Protect locallyClient SDKLoopback sidecar 03InspectFinancial policyResidual patterns 04ValidateStrict schemaExtra denied 05AuditMetadataNo bodies Configured residual detector coverage passed.Local protection remains the preferred first boundary. Detected → rejectNo financial calculation runs
Figure 4. Defense in depth combines local protection, residual inspection, schema minimization, and metadata-only domain audit.
PreferredClient or sidecar tokenization before transfer
Server controlBest-effort configured detector coverage
Failure modeReject detected residual values before calculation
Audit scopeDomain table excludes request and response bodies
09

AUDIT RECEIPTS

Record execution facts without making the audit table a data lake.

Each completed or rejected domain workflow writes a metadata-oriented audit record. Retrieval is scoped to the API key that created the run. The domain record does not contain holdings, questionnaire ratings, citations, monetary values, or analysis output.

DOMAIN RUN RECEIPTdom_••••••••••••
TimestampUTC execution time
EndpointFinancial route
AgentVersioned agent ID
Privacy modeoff / client / sidecar / hosted
Status + durationOutcome metadata
Schema namesInput + output contract
CountsSources + warnings
Methodologygrandice-domain-1.0.0
EXCLUDED request body · response body · citations · financial values · generated analysis

“Body-free domain audit” describes the Grandice domain_runs record. It does not characterize every surrounding reverse proxy, application, infrastructure, security, or client log.

10

DECISION GOVERNANCE

Calculation ends where accountable judgment begins.

Calculation and decision boundary Caller-supplied factsDated · cited · validated Deterministic calculationVersioned methodology Metrics + flags + disclosuresSources · assumptions · limitations · warningsprofessional_review_required: true DECISION BOUNDARY Qualified professional + firm policyVerify, contextualize, supervise, approve or reject Institution-controlled useCommunication or action, if approved GRANDICEprovides reproducibleanalysis artifactsINSTITUTIONowns the decision
Figure 5. The professional-review flag is a response invariant. The current API does not perform, verify, or record completion of institutional review.

Recommended downstream review

  1. Confirm source identity, dates, completeness, and authority.
  2. Reconcile totals and period values to systems of record.
  3. Validate classifications, currency consistency, and denominator rules.
  4. Review triggered flags, omitted ratios, assumptions, and limitations.
  5. Apply firm-approved suitability, supervisory, legal, and compliance processes.
  6. Record reviewer identity, disposition, and any decision in the institution’s system.
11

INTEGRATION PATTERNS

Embed analysis inside existing controlled workflows.

ADVISER WORKSTATION

Concentration screening

A portfolio system submits dated, locally tokenized holdings using opaque instrument IDs. Grandice returns allocation and concentration indicators. The adviser determines whether further analysis or communication is appropriate.

RISK INTAKE

Transparent questionnaire scoring

A firm-approved questionnaire maps responses to five bounded ratings. Grandice calculates the disclosed score and band. A separate supervisory workflow decides how, or whether, the result may be used.

EQUITY RESEARCH

Historical ratio pipeline

An analyst or controlled ETL process supplies at least two cited periods. Grandice computes supported ratios. Analysts reconcile values and add qualitative, forecast, peer, and market context outside the service.

DEVELOPER PLATFORM

Direct API or registry dispatch

Applications can call a known financial endpoint or discover and invoke a managed agent through a common envelope. Both paths preserve request ID, methodology, sources, warnings, and review requirements.

DIRECTPOST /v1/financial/portfolio/analyze
DIRECTPOST /v1/financial/risk-assessment
DIRECTPOST /v1/financial/company/analyze
REGISTRYGET /v1/agents
DISPATCHPOST /v1/agents/runs
AUDITGET /v1/domain/runs/{request_id}
12

RUNTIME CONTROLS

Resource and schema limits narrow the operating envelope.

2 MiBmaximum domain request
14maximum JSON levels
25,000maximum JSON values
5,000maximum positions
100maximum periods or sources
34maximum decimal digits

Exact decimal contract

Monetary values arrive as JSON strings or integers. Binary JSON floats, non-finite numbers, excessive magnitude, and excessive scale are rejected.

Strict schema contract

Extra fields, duplicate source IDs, unresolved references, inconsistent dates, duplicate instruments, and duplicate periods are rejected.

Sanitized failures

Validation responses describe field locations and rules without echoing rejected input values or validator context.

Rate and tenancy controls

API-key controls and configured member or organization limits run before JSON parsing. Audit retrieval requires the originating API key.

13

EVALUATION ROADMAP

Implementation is the start of assurance—not evidence of production fitness.

The following staged program is proposed. It is not a claim that these activities are complete.

PHASE 1

Calculation assurance

  • Independent golden vectors
  • Threshold boundary tests
  • Property-based invariants
  • Spreadsheet/reference comparison
  • Methodology-version regression
PHASE 2

Schema + provenance

  • Malformed JSON fuzzing
  • Source/date mismatch tests
  • Coercion and float rejection
  • Error redaction verification
  • Cross-key receipt isolation
PHASE 3

Privacy evaluation

  • Labeled detector corpora
  • Precision and recall by entity
  • Obfuscation variants
  • Financial false positives
  • Policy regression fixtures
13B

EVALUATION ROADMAP · CONTINUED

Methodology, operations, and institutional adoption.

PHASE 4

Methodology review

  • Qualified practitioner challenge
  • Weights and threshold review
  • Population and use boundaries
  • Misinterpretation testing
  • Change-approval governance
PHASE 5

Operational readiness

  • Load and failure-mode tests
  • Security and threat modeling
  • Surrounding-log review
  • Recovery and rollback
  • Incident response
PHASE 6

Institution validation

  • Legal and compliance review
  • Representative UAT
  • Reviewer workflow testing
  • Controlled pilot
  • Ongoing monitoring
14

CURRENT LIMITATIONS

Known boundaries should travel with the output.

Portfolio

  • No covariance, volatility, drawdown, liquidity, tax, fee, or look-through modeling.
  • Caller classifications and comparable positive values are assumed.
  • Screening thresholds are policy indicators, not recommendations.

Risk

  • Five caller-scored dimensions with fixed weights.
  • No psychometric validation or adaptive scoring.
  • Cannot be used alone for suitability or product selection.
14B

CURRENT LIMITATIONS · CONTINUED

Analytical and platform exclusions.

Company

  • No forecasts, peer context, accounting normalization, restatement handling, or one-time adjustments.
  • Multiples are omitted where inputs or positive denominators are unavailable.
  • Point-in-time arithmetic is not a valuation opinion.

Platform

  • Detector coverage is policy-based and should be evaluated against each institution’s representative data.
  • Sources are attributed but not independently verified.
  • Initial agents do not browse, stream, trade, or invoke external tools.
15

CONCLUSION

Useful automation can be narrow, explicit, and accountable.

Grandice demonstrates a deliberately constrained approach to financial agents: typed workflow dispatch, deterministic arithmetic, caller-supplied provenance, best-effort privacy residual checks, metadata-only domain receipts, and an explicit professional-review boundary.

Its value proposition is controlled analytical consistency and integration—not autonomous judgment. Institutional deployment still requires use-case-specific validation, governance, security review, legal and compliance assessment, methodology approval, and qualified human supervision.

REPRODUCIBLE CALCULATIONEXPLICIT LIMITSHUMAN ACCOUNTABILITY
A

APPENDIX

Response invariants and implementation references

{
  "request_id": "dom_...",
  "privacy": {
    "mode": "client",
    "residual_check": {
      "status": "passed",
      "coverage": "configured_policy_detectors",
      "guarantee": "best_effort"
    },
    "content_retained": false
  },
  "data": {
    "methodology_version": "grandice-domain-1.0.0",
    "assumptions": ["..."],
    "limitations": ["..."],
    "warnings": ["..."],
    "professional_review_required": true
  }
}
grandice_domain/common.pyShared contracts, decimal bounds, disclosures, methodology version
grandice_domain/portfolio.pyPortfolio arithmetic and concentration rules
grandice_domain/risk.pyWeighted score and band methodology
grandice_domain/company.pyHistorical ratios, leverage, and supported multiples
grandice_domain/agents.pyVersioned agent registry and authority declarations
gateway/domain_runtime.pyRequest bounds, privacy check, audit write, response envelope
Important notice

This document describes the September 2026 initial implementation. It is technical product documentation, not legal, regulatory, investment, accounting, tax, or compliance advice. Capabilities, controls, and methodology may change under future versioning. Adopting institutions must perform their own review and validation.