Content
List
This is a Java-based intelligent underwriting demo for insurance, designed for interview explanations and local learning. The project showcases a complete, runnable, and trackable chain: user problem understanding → internal data query → RAG knowledge retrieval → risk analysis rule verification → large model suggestions → result persistence.
By default, the configuration is completely offline fictional data, Hash Embedding, in-memory vector library, and deterministic Mock models, **no API Key** required, no database or external models needed to start. All company names, addresses, terms, and policies are fictional examples and do not contain real business data.
## Tech Stack
- Java 21, Maven
- 4.1,, Bean Validation, Actuator Spring AI 2.0 MCP Server, Streamable HTTP `/mcp`
- OpenAI-compatible1/chat/completions`
- springdoc OpenAPI / Swagger UI
- JUnit 5, AssertJ, MockMvc, MockWebServer
## What Can Showcase
- Session Management: create/restore sessions user and assistant messages by role.
- Agent Orchestration: fixed seven-step pipeline, retain step trajectory on success or failure.
AG: Markdown/Text parsing, paragraph splitting, overlapping windows,, storage, cosine similarity retrieval, and metadata filtering.
- Business Tools: policy, quote, historical underwriting, survey report, disaster risk, and rule verification six types of tools, sharing a unified registry and audit trail.
- Rule Baseline: models can only explain rule results, not downgrade `MANUAL_REVIEW` or `REJECT` to automatic approval.
Switching: default Mock; can switch to OpenAI-compatible interface or enterprise privatized gateway, supporting connection/read timeout, limited retries, and explicit downgrade.
- Prompt Governance: versioning, activation version, variable declaration check, and preview rendering.
- REST + MCP: REST for management and debugging, MCP for agent tool discovery and invocation, sharing the same business implementation.
- Chinese Interaction Demo: no need to copy commands, choose four fictional scenarios, run real underwriting, and read rules, evidence, and seven-step trajectory.
- Chinese Under: export saved single assessment to Markdown, retaining conclusions, evidence, seven-step tool records, and model## Quick Start
Pr Java 21+ and Maven 3.9+.
```bash
mvn clean verify
mvn spring-boot:```
Open a new terminal to check the service:
```curl --fail http://localhost:8080/actuatorbash scripts/demo.sh
```
Access via browser:
- Chinese Intelligent Underwriting Demo: <http://localhost:8080/demo/> (recommended for first experience)
- Swagger UI: <http://localhost:8080/swagger-ui/index.html>
- OpenAPI JSON: <http://localhost:8080/v3/api-docs>
- Fictional Scenario Directory: <http://localhost:8080/api/v1/demo/scenarios>
- MCP Streamable HTTP: `http:8080/mcp`
### Browser Interaction Demo (Recommended launching the application, visit <http://localhost:8080 to enter the "Chinese Intelligent Underwriting Demo".
1. Select any fictional scenario from `P-1001` to `P-4001` on the left;
2. Read policy, quote, history, survey, and disaster business facts;
3. Click "Run Intelligent" to view actual conclusions, expected conclusions, rule hits,, and seven-step execution trajectory;
4. Click "Download Chinese Markdown Report" to save the auditable results of the current assessment;
5. Click "Compare All Scenarios" to let four groups of fictional policies call the same real underwriting interface in sequence;
6. Confirm from the comparison overview that approval, 2 manual reviews, 1 rejection, risk scores ranging from 10–70 then enter any scenario to view five types of facts.
All page data comes from `underwriting-scenarios.json`, only for teaching and interview demonstration, not for real underwriting judgment. The page does not replicate business judgments but calls the same underwriting service as the API.
Horizontal comparison does not read precomputed static conclusions: all four cards real-time `POST /1/underwriting/evalu If a single group request fails, the page retains other successful results and displays an independent failure card.
The download link only appears after a single scenario assessment is successful. The backend reads the saved result corresponding to the assessment number to generate the report, without re-executing the model or rules; switching scenarios immediately clears the old link to avoid downloading the wrong report.
## 10-Minute Learning Route
1. Run `mvn clean verify` to environment and all tests pass. Run `mvn spring-boot:run` to start the offline service.
3. Open `/demo/`, click "Compare All Scenarios" to understand the conclusion then enter a scenario to underwriting.
4.api/v1/demo/scenarios` to compare page data, then run `bash scripts/demo.sh` to observe batch API processes.
5. Refer to [Fictional Underwriting Data and 10-Minute Learning Guide](docs/DEMO_DATA_GUIDE.md) to track from business facts to rule hits, risk scoring, and final decisions.
## Four Teaching Demo Scenarios
| Policy No. | Scenario | Key Facts | Deterministic Result |
|---|---|---|---|
| `P-1001 High-risk logistics warehouse in Lingang | 20 million CNY coverage, 2 claims in 3 years, drainage improvement not completed, red storm risk | Manual Review (`MANUAL_REVIEW`), High Risk (`HIGH`), 70 points |
| `P-2001` | Low-risk tech office building | 5 million CNY coverage, no historical claims, no survey, low disaster risk | Automatic Approval (`APPROVE sufficient evidence, Low Risk (`LOW`), 10 points |
| `P-3001` | Storm-exposed commercial warehouse | 12 million CNY coverage, 1 claim, improvement completed, red storm risk | Manual Review (`MANVIEW`), Medium Risk (`MEDIUM`), 40 points `P-4001 Extreme fire risk manufacturing plant | 8 million CNY coverage, major fire defects, extreme fire risk | Rejection (`REJECT`), High Risk (`HIGH`), 60 points |
When knowledge evidence is missing, even if the rules originally allow automatic approval, the system will elevate the decision threshold to `MANUAL_REVIEW` to avoid unsubstantiated automatic underwriting.
## Seven-Step Orchestration
```text
QUESTION_UNDERSTANDING
-> BUSINESS_DATA_COLLECTION
-> KNOWLEDGE_RETRIEVAL
-> RISK_ANALYSIS
-> RULE_VALIDATION
-> RECOMMENDATION_GENERATION
-> RESULT_PERSISTENCE
```
A complete assessment returns: final decision, risk level/score, hit rules, knowledge evidence, model summary, suggested actions, 5 business data tool calls + 1 rule tool call, and 7 step trajectories.
## Model Switching
Default `LLM_PROVIDER=mock`, no network access. When connecting to OpenAI-compatible or enterprise privatized interfaces:
```bash
export LLM_PROVIDER=openai-compatible
export LLM_BASE_URL=https://your-model-gateway.example.com
export LLM_API_KEY=replace-with-runtime-secret
export LLM_MODEL=your-model-name
export LLM_CONNECT_TIMEOUT=2s
export LLM_READ_TIMEOUT=15s
export LLM_MAX_ATTEMPTS=3
export LLM_RETRY_BACKOFF=100ms
export LLM_FALLBACK_TO_MOCK=false
mvn spring-boot:run
```
Only retries for I/O exceptions, timeouts, HTTP 429, and 5xx; not for ordinary 4xx. Default prohibits silent downgrade. Only explicitly set `LLM_FALLBACK_TO_MOCK=true` to fallback and mark `fallbackUsed=true` in the response. API Key only reads from runtime environment, no logging, no response, no exception.
## Docker
```bash
docker build -t insurance-underwriting-agent-demo:local .
docker run --rm -p 8080:8080 insurance-underwriting-agentlocal
```
The container uses Java 21 runtime, user, and health checks. Default remains Mock mode without external dependencies.
## Project Structure
```text
src/main/java/com/hrniux/underwriting
├── agent # Seven-step orchestration, assessment results, and step trajectories
├── api # REST controllers and request DTOs
├── demo # Structured fictional scenarios, integrity verification, and Chinese directory API
├── model # Mock/OpenAI-compatible/routing model gateway
├── prompt # Prompt version management and strict rendering
├── rag # Document parsing, splitting, Embedding, vector retrieval
├── report # Chinese Markdown underwriting report and security escaping
├── rule # Deterministic rules, risk scoring, and decision thresholds
├── session # Sessions and messages
├── tool # Fictional internal systems, registry, MCP tools
└── shared # Configuration and unified exceptions
```
Further reading:
- [Fictional Underwriting Data and 10-Minute Learning Guide](docs/DEMO_DATA_GUIDE.md)
- [Architecture and Key Design](docs/ARCHITECTURE.md)
- [ / MCP Examples/API_EXAMPLES.md)
- [Interview Demo and Q&A/INTERVIEW_G.md)
## Production Evolution
This project intentionally separates port and memory implementation for clear production transformation:
| Demo Implementation | Production Replacement Direction |
|---|---|
| In-memory session/assessment repository | Redis session + PostgreSQL audit and assessment tables |
| Hash Embedding | Enterprise Embedding model or compliant cloud model |
| In-memory vector library | PostgreSQL + PGVector, Milvus, or Elasticsearch |
| JSON scenario repository + fictional tools | Real API adapters for policy, quote, underwriting, survey, disaster platforms, and rule engines |
| Single-machine synchronous orchestration | State machine/workflow engine, message queue, idempotent key, timeout compensation Environment variable secrets | Vault/KMS, short-term credentials, key rotation, and exit gateway |
| Single-instance metrics | Micrometer, Prometheus, OpenTelemetry Trace cost, and recall quality dashboard |
Production environments should also add tenant/institution permissions, field-level desensitization, operation audit, knowledge release approval, Prompt grayscale, model output evaluation, artificial feedback loop, and disaster recovery strategies.
## Disclaimer
This project is for technical learning and interview demonstration only and does not constitute real insurance underwriting opinions. Example data, rule thresholds, and terms are all fictional.
