5. Building Block View
Level 1: System Overview
Level 2: Component Details
Smitty AI Agent
Purpose: Autonomous AI economist that orchestrates sentiment analysis and learns from outcomes.
Responsibilities:
- Analyze 6 sentiment layers (macro, micro, geopolitical, capital markets, demographics, events)
- Calculate weighted sentiment scores based on asset type
- Learn from historical valuation outcomes
- Self-correct weighting based on prediction accuracy
- Generate explainable AI reports for regulators
Interfaces:
- Input: Valuation request (property details, location, asset type)
- Output: Sentiment score (-100 to +100), layer breakdown, confidence interval
- Feedback: Post-valuation market outcome data
Technology:
- Python 3.11+
- LangChain for agent framework
- OpenAI GPT-4 for reasoning
- Custom memory retrieval system
Internal Structure:
Key Algorithms:
- Weighted Sentiment Aggregation:
Final_Score = Σ (Layer_Score_i × Weight_i × Asset_Factor_i) - Weight Optimization: Gradient descent on historical prediction error
- Confidence Calculation: Based on data freshness, layer agreement, historical accuracy
CRESI Calculator
Purpose: Fetches and normalizes data from 6 sentiment layers.
Responsibilities:
- Fetch data from external APIs (FRED, CoStar, news sources)
- Normalize scores to -100 to +100 scale
- Handle API failures gracefully (fallback to cached data)
- Aggregate layer scores with asset-specific weights
Interfaces:
- Input: Property location (MSA, zip), asset type (office, retail, industrial, multifamily)
- Output: 6 layer scores, data freshness timestamps, confidence metrics
Data Sources:
| Layer | Primary Source | Backup Source | Update Frequency |
|---|---|---|---|
| Macro | FRED API | BEA API | Daily |
| Micro | CoStar | REIS | Weekly |
| Geopolitical | News APIs | Manual curation | Real-time |
| Capital Markets | NCREIF | Green Street | Monthly |
| Demographics | Census API | Moody's Analytics | Quarterly |
| Events | NewsAPI.org | Custom scraping | Hourly |
Caching Strategy:
- Layer data cached for 24 hours (macro, micro, demographics)
- Events data cached for 1 hour
- Cache invalidation on explicit refresh request
Memory Bank
Purpose: Store historical valuations and outcomes for continuous learning.
Responsibilities:
- Record each valuation request and Smitty's prediction
- Store actual market outcomes (sales, lease rates, occupancy)
- Provide historical data for weight optimization
- Generate accuracy metrics over time
Data Model:
Storage:
- PostgreSQL 15+ with TimescaleDB extension
- Partitioned by month for query performance
- Retention: 7 years (FINRA compliance)
Analytics Queries:
- Prediction accuracy by asset type
- Layer importance trending over time
- Geographic performance patterns
- Model drift detection
Web Application
Purpose: User interface for lenders and appraisers.
Responsibilities:
- Submit valuation requests
- Display sentiment score breakdowns
- Provide layer-by-layer explanations
- View historical accuracy metrics
- Export reports for regulatory review
Technology:
- React 18+
- TypeScript
- Tailwind CSS
- Recharts for visualizations
Key Views:
- Request Form: Property details, asset type, valuation purpose
- Results Dashboard: Sentiment score, layer breakdown, confidence interval
- Explainability View: Why each layer scored as it did
- History Log: Past valuations and accuracy tracking
- Admin Panel: Weight tuning, data source health monitoring
API Gateway
Purpose: Routing, authentication, rate limiting for all API requests.
Responsibilities:
- Route requests to appropriate services
- Validate JWT tokens
- Enforce rate limits (100 req/min per client)
- Log all API calls for audit trail
- Handle CORS for web application
Technology:
- Node.js + Express
- express-rate-limit middleware
- winston for logging
- helmet for security headers
Authentication Service
Purpose: User identity and access management.
Responsibilities:
- User registration and login
- OAuth 2.0 / OIDC integration
- Role-based access control (Lender, Appraiser, Admin, Auditor)
- Session management
- Audit logging of authentication events
Technology:
- Auth0 (managed service)
- SAML 2.0 for enterprise SSO
- MFA via SMS or authenticator app
Roles and Permissions:
| Role | Permissions |
|---|---|
| Lender | Submit requests, view own valuations, export reports |
| Appraiser | Submit requests, view all valuations, access raw layer data |
| Admin | All permissions + weight tuning, user management |
| Auditor | Read-only access to all data, export audit logs |
Level 3: Component Internals
Smitty Agent Internal Components
Layer Orchestrator:
- Spawns parallel async tasks for 6 layer fetches
- Timeout handling (30s max per layer)
- Retry logic with exponential backoff
- Aggregates results when all layers complete
Weight Optimizer:
- Batch processing (nightly) of previous day's outcomes
- Gradient descent on mean absolute percentage error (MAPE)
- Asset-specific weight matrices
- Constraints: weights sum to 1.0, all weights ≥ 0.05
Explainability Module:
- SHAP values for layer contribution importance
- Human-readable narrative generation
- Regulatory compliance report formatting
For runtime behavior of these components, see Runtime View. For deployment topology, see Deployment View.