Add Hedging Functionality to the portfolio management tool

[manu49]

Summary

This PR adds a new suggest_portfolio_hedge agent tool to the Agentic Financial Service Assistant (AFSA) demo app. The tool analyses a portfolio's risk factors and recommends specific hedging instruments, giving financial advisors an AI-assisted starting point for downside protection conversations.

It also establishes the project's first testing infrastructure — from scratch — covering the full stack from the backend recommendation engine through to the React frontend component rendering.

---

What's New

New Agent Tool: suggest_portfolio_hedge

Users can now ask the agent questions like:

• "What hedges would you recommend for ACC-003?"
• "How can I protect this portfolio against sector concentration risk?"
• "Suggest currency hedges for ACC-010"

How it works:

A single Oracle SQL query (Relational + JSON + window-function analytics) fetches the full risk picture for an account — sector breakdown, regional exposure, asset class distribution, high-risk positions (rating ≥ 7), and ESG mandate from JSON metadata — in one statement. A pure-Python recommendation engine then maps detected risk factors to a curated catalogue of hedging instruments.

Risk dimensions covered (controlled by the optional risk_focus parameter):

Dimension	Trigger	Example instruments
market	Equity > 60% of portfolio, or high-risk positions present	SH (inverse S&P500), GLD, TLT
sector	Any sector > 30% concentration	QQQ puts, sector inverse ETFs, VXUS
regional	Any region > 50% concentration	EFA, ACWX, EPV
currency	> 25% international exposure	UUP, FXE
all	All of the above (default)	Combined set, de-duplicated

ESG-aware: accounts with an ESG mandate have leveraged and high-risk instruments automatically filtered out of recommendations.

Both architecture modes supported: Oracle converged mode (tools.py) and PostgreSQL sprawl mode (sprawl_tools.py).

---

Test Suite (first tests in this project)

Sets up testing infrastructure from scratch and adds 97 tests across the full stack.

Backend — pytest (backend/tests/)

File	Tests	Coverage
test_hedge_recommendations.py	39	Pure-unit tests for _build_hedge_recommendations: output structure, all four risk dimensions, ESG filtering, risk_focus scoping, edge cases (empty rows, None PCTs, malformed JSON)
test_suggest_portfolio_hedge_integration.py	8	Full _suggest_portfolio_hedge pipeline with a mock execute_query — JSON output, error messages, default args, query logger invocation, SQL param binding
test_tool_schema.py	11	Schema registration in TOOL_SCHEMAS and PRELOADED_TOOLS, required/optional params, enum values, dispatcher routing

Run with:

cd backend
pip install -r requirements.txt
pytest tests/ -v

Frontend — Vitest + @testing-library/react (frontend/src/test/)

File	Tests	Coverage
ToolCallBubble.test.jsx	22	Running/success/error states, expand/collapse toggle, pretty-printed JSON output, args rendering edge cases
chatReducer.test.js	17	Full WebSocket lifecycle: ADD_TOOL_CALL_START → UPDATE_TOOL_CALL → AGENT_COMPLETE, tool calls attached to assistant messages, isLoading cleared, multi-tool isolation

Run with:

cd frontend
npm install
npm test

---

Files Changed

backend/agent/tools.py              — tool schema, Oracle implementation, hedge catalogue + engine
backend/agent/sprawl_tools.py       — PostgreSQL sprawl-mode implementation
backend/tests/__init__.py
backend/tests/conftest.py           — shared pytest fixtures (4 portfolio scenarios)
backend/tests/test_hedge_recommendations.py
backend/tests/test_suggest_portfolio_hedge_integration.py
backend/tests/test_tool_schema.py
backend/pytest.ini
backend/requirements.txt            — added pytest, pytest-mock
frontend/vite.config.js             — vitest config (jsdom, coverage)
frontend/package.json               — test/test:watch/test:coverage scripts
frontend/src/test/setup.js
frontend/src/test/hedgeFixtures.js  — shared ToolCall fixtures
frontend/src/test/ToolCallBubble.test.jsx
frontend/src/test/chatReducer.test.js

Checklist

• Code formatted with Ruff (Python) and Prettier (JS/JSX) — passes ruff check and prettier --check
• All 97 tests pass (58 backend, 39 frontend)
• Both Oracle converged and PostgreSQL sprawl modes implemented
• ESG mandate filtering applied to recommendations
• Output includes a disclaimer that recommendations are algorithmic and require advisor review
• Oracle Contributor Agreement signed (required before merge — see OCA)

[oracle-contributor-agreement]

Thank you for your pull request and welcome to our community! To contribute, please sign the Oracle Contributor Agreement (OCA).
The following contributors of this PR have not signed the OCA:

• PR author: manu49
• noreply@anthropic.com (@claude)

To sign the OCA, please create an Oracle account and sign the OCA in Oracle's Contributor Agreement Application.

When signing the OCA, please provide your GitHub username. After signing the OCA and getting an OCA approval from Oracle, this PR will be automatically updated.

If you are an Oracle employee, please make sure that you are a member of the main Oracle GitHub organization, and your membership in this organization is public.