Feat/abstraction

.aiguidance/ai-guidelines.md

@@ -0,0 +1,386 @@
+# AI Guidelines for VeritasVault.net
+
+## Table of Contents
+
+- [AI Guidelines for VeritasVault.net](#ai-guidelines-for-veritasvaultnet)
+  - [Table of Contents](#table-of-contents)
+  - [Overview](#overview)
+  - [Core Principles](#core-principles)
+  - [Implementation Guidelines](#implementation-guidelines)
+    - [AI Component Architecture](#ai-component-architecture)
+    - [User Experience Guidelines](#user-experience-guidelines)
+  - [AI Features in VeritasVault.net](#ai-features-in-veritasvaultnet)
+    - [Risk Assessment](#risk-assessment)
+    - [Portfolio Optimization](#portfolio-optimization)
+    - [Market Analysis](#market-analysis)
+    - [Anomaly Detection](#anomaly-detection)
+  - [Development Workflow](#development-workflow)
+  - [Ethical Considerations](#ethical-considerations)
+  - [Compliance](#compliance)
+  - [Updates to These Guidelines](#updates-to-these-guidelines)
+
+## Overview
+
+This document outlines the guidelines and best practices for AI integration within the VeritasVault.net platform. These guidelines ensure consistent, ethical, and effective use of AI technologies across our enterprise liquidity management solutions.
+
+## Core Principles
+
+1. **Transparency**: All AI-driven decisions and recommendations should be explainable and transparent to users.
+2. **Accuracy**: AI models should be regularly evaluated and validated for accuracy and reliability.
+3. **Data Privacy**: AI systems must adhere to strict data privacy standards and regulations.
+4. **User Control**: Users should maintain control over AI features and be able to override automated decisions.
+5. **Continuous Improvement**: AI systems should be designed to learn and improve over time based on feedback.
+
+## Implementation Guidelines
+
+### AI Component Architecture
+
+1. **Separation of Concerns**:
+
+   - AI logic should be separated from UI components
+   - Use dedicated services for AI processing
+   - Implement clear interfaces between AI services and the rest of the application
+
+   **Example: AI Service Interface**
+
+   ```typescript
+   // src/services/ai/interfaces.ts
+   export interface AIService<T, R> {
+     process(input: T): Promise<AIResult<R>>;
+     getConfidenceScore(): number;
+     explainResult(result: AIResult<R>): string;
+   }
+
+   export interface AIResult<T> {
+     data: T;
+     confidence: number;
+     timestamp: Date;
+     modelVersion: string;
+     explanation?: string;
+   }
+   ```
+
+2. **Client-Server Considerations**:
+
+   - Heavy AI processing should occur on the server side
+   - Client-side AI should be limited to lightweight inference
+   - Consider using Web Workers for client-side AI to prevent UI blocking
+
+   **Example: Web Worker Setup**
+
+   ```javascript
+   // src/workers/anomalyDetection.worker.js
+   self.onmessage = async (event) => {
+     const { timeseriesData, threshold } = event.data;
+
+     // Perform lightweight anomaly detection
+     const anomalies = detectAnomalies(timeseriesData, threshold);
+
+     // Return results to main thread
+     self.postMessage({ anomalies, processingTime: performance.now() });
+   };
+
+   // Usage in component
+   const anomalyWorker = new Worker(
+     new URL("./anomalyDetection.worker.js", import.meta.url),
+   );
+   anomalyWorker.onmessage = (event) => {
+     setAnomalies(event.data.anomalies);
+     setIsProcessing(false);
+   };
+   ```
+
+3. **Next.js Integration**:
+
+   - Use server components for AI data processing
+   - Wrap client components using AI hooks in Suspense boundaries
+   - Implement proper error boundaries for AI components
+
+   **Example: Next.js AI Component Pattern**
+
+   ```tsx
+   // app/portfolios/[id]/risk-assessment/page.tsx
+   import { Suspense } from "react";
+   import { AIErrorBoundary } from "@/components/error-boundaries";
+   import { RiskAssessmentSkeleton } from "@/components/skeletons";
+   import { RiskAssessmentComponent } from "@/components/risk-assessment";
+
+   export default function RiskAssessmentPage({
+     params,
+   }: {
+     params: { id: string };
+   }) {
+     return (
+       <div className="risk-container">
+         <h1>Portfolio Risk Assessment</h1>
+
+         <AIErrorBoundary
+           fallback={
+             <div>
+               Unable to generate risk assessment. View manual analysis instead.
+             </div>
+           }
+         >
+           <Suspense fallback={<RiskAssessmentSkeleton />}>
+             <RiskAssessmentComponent portfolioId={params.id} />
+           </Suspense>
+         </AIErrorBoundary>
+       </div>
+     );
+   }
+   ```
+
+### User Experience Guidelines
+
+1. **Loading States**:
+
+   - Always provide clear loading indicators for AI operations
+   - Consider skeleton screens for AI-populated content
+   - Implement progressive loading for AI-heavy dashboards
+
+2. **Error Handling**:
+
+   - Provide graceful fallbacks when AI services fail
+   - Offer manual alternatives to automated AI features
+   - Communicate errors in user-friendly language
+
+   **Example: Error Boundary Implementation**
+
+   ```tsx
+   // components/error-boundaries.tsx
+   "use client";
+
+   import { Component, ErrorInfo, ReactNode } from "react";
+   import { reportAIError } from "@/lib/monitoring";
+
+   interface Props {
+     children: ReactNode;
+     fallback: ReactNode;
+   }
+
+   interface State {
+     hasError: boolean;
+     error?: Error;
+   }
+
+   export class AIErrorBoundary extends Component<Props, State> {
+     constructor(props: Props) {
+       super(props);
+       this.state = { hasError: false };
+     }
+
+     static getDerivedStateFromError(error: Error): State {
+       return { hasError: true, error };
+     }
+
+     componentDidCatch(error: Error, errorInfo: ErrorInfo): void {
+       reportAIError({
+         error,
+         component: errorInfo.componentStack,
+         timestamp: new Date(),
+       });
+     }
+
+     render() {
+       if (this.state.hasError) {
+         return this.props.fallback;
+       }
+
+       return this.props.children;
+     }
+   }
+   ```
+
+3. **Feedback Mechanisms**:
+   - Allow users to provide feedback on AI recommendations
+   - Track and analyze user interactions with AI features
+   - Implement mechanisms to report and address AI inaccuracies
+
+## AI Features in VeritasVault.net
+
+### Risk Assessment
+
+- Implement confidence scores with all risk assessments
+- Provide detailed explanations for risk categorizations
+- Allow users to adjust risk parameters and see updated assessments
+
+### Portfolio Optimization
+
+- Clearly indicate when recommendations are AI-generated
+- Show the reasoning behind allocation recommendations
+- Allow users to set constraints for optimization algorithms
+
+### Market Analysis
+
+- Distinguish between factual market data and AI predictions
+- Provide historical accuracy metrics for predictive features
+- Update prediction models regularly with new market data
+
+### Anomaly Detection
+
+- Set appropriate thresholds to minimize false positives
+- Provide context for detected anomalies
+- Implement user feedback for anomaly reports
+
+## Development Workflow
+
+1. **Testing AI Components**:
+
+   - Create specific test cases for AI functionality
+   - Test with diverse and edge-case data
+   - Implement A/B testing for new AI features
+
+   **Example: AI Component Test**
+
+   ```typescript
+   // __tests__/ai/risk-assessment.test.ts
+   import { RiskAssessmentService } from "@/services/ai/risk-assessment";
+
+   describe("Risk Assessment Service", () => {
+     const mockPortfolio = {
+       id: "port-123",
+       assets: [
+         { type: "equity", ticker: "AAPL", allocation: 0.2 },
+         { type: "fixed_income", ticker: "BND", allocation: 0.5 },
+         { type: "crypto", ticker: "BTC", allocation: 0.3 },
+       ],
+     };
+
+     it("should provide risk scores for all asset classes", async () => {
+       const service = new RiskAssessmentService();
+       const result = await service.process(mockPortfolio);
+
+       expect(result.data.overallRiskScore).toBeDefined();
+       expect(result.data.assetClassRisks).toHaveProperty("equity");
+       expect(result.data.assetClassRisks).toHaveProperty("fixed_income");
+       expect(result.data.assetClassRisks).toHaveProperty("crypto");
+       expect(result.confidence).toBeGreaterThan(0.7);
+     });
+
+     it("should identify high-risk assets correctly", async () => {
+       const service = new RiskAssessmentService();
+       const result = await service.process(mockPortfolio);
+
+       expect(result.data.highRiskAssets).toContain("BTC");
+     });
+   });
+   ```
+
+2. **Versioning**:
+
+   - Track AI model versions in application code
+   - Document changes between model versions
+   - Implement feature flags for new AI capabilities
+
+3. **Monitoring**:
+
+   - Log AI performance metrics
+   - Track user engagement with AI features
+   - Monitor for drift in AI model accuracy
+
+4. **CI/CD Integration**:
+
+   - Automate AI model testing with each code change
+   - Implement quality gates for AI performance metrics
+   - Include AI-specific resources in infrastructure as code
+
+   **Example: GitHub Actions Workflow for AI Testing**
+
+   ```yaml
+   # .github/workflows/ai-model-tests.yml
+   name: AI Model Testing
+
+   on:
+     push:
+       branches: [main]
+       paths:
+         - "src/services/ai/**"
+         - "models/**"
+     pull_request:
+       branches: [main]
+
+   jobs:
+     test:
+       runs-on: ubuntu-latest
+
+       steps:
+         - uses: actions/checkout@v3
+
+         - name: Set up Node.js
+           uses: actions/setup-node@v3
+           with:
+             node-version: "20"
+             cache: "npm"
+
+         - name: Install dependencies
+           run: npm ci
+
+         - name: Run AI unit tests
+           run: npm run test:ai
+
+         - name: Run AI model performance benchmark
+           run: npm run benchmark:ai
+
+         - name: Verify model accuracy is above threshold
+           run: node scripts/verify-model-accuracy.js --threshold=0.85
+
+         - name: Report AI test metrics
+           if: always()
+           run: node scripts/report-ai-metrics.js
+           env:
+             METRICS_API_KEY: ${{ secrets.METRICS_API_KEY }}
+   ```
+
+## Ethical Considerations
+
+1. **Fairness**:
+
+   - Regularly audit AI systems for bias
+   - Test with diverse data representing all user groups
+   - Implement fairness metrics in AI evaluation
+
+2. **Accountability**:
+
+   - Clearly define responsibility for AI-driven decisions
+   - Maintain audit trails for critical AI operations
+   - Establish review processes for AI systems
+
+3. **Sustainability**:
+   - Optimize AI models for computational efficiency
+   - Consider environmental impact of training and inference
+   - Balance model complexity with resource usage
+
+## Compliance
+
+1. **Regulatory Adherence**:
+
+   - Ensure AI systems comply with financial regulations
+   - Maintain documentation for regulatory review
+   - Implement controls for regulated AI use cases
+
+   **Regulatory References:**
+
+   - [SEC 17 CFR § 275.204-2(a)(16)](https://www.ecfr.gov/current/title-17/section-275.204-2) - Books and records to be maintained by investment advisers
+   - [GDPR Article 22](https://gdpr-info.eu/art-22-gdpr/) - Automated individual decision-making, including profiling
+   - [FINRA Regulatory Notice 21-25](https://www.finra.org/rules-guidance/notices/21-25) - Artificial Intelligence in the Securities Industry
+   - [Federal Reserve SR Letter 11-7](https://www.federalreserve.gov/supervisionreg/srletters/sr1107.htm) - Guidance on Model Risk Management
+
+2. **Data Governance**:
+
+   - Establish clear data retention policies for AI training
+   - Document data lineage for AI models
+   - Implement data minimization practices
+
+   **Regulatory References:**
+
+   - [GDPR Article 5](https://gdpr-info.eu/art-5-gdpr/) - Principles relating to processing of personal data
+   - [CCPA §1798.100](https://leginfo.legislature.ca.gov/faces/codes_displaySection.xhtml?lawCode=CIV&sectionNum=1798.100) - Consumer right to know
+   - [NY DFS 23 NYCRR 500](https://www.dfs.ny.gov/industry_guidance/cybersecurity) - Cybersecurity Requirements for Financial Services Companies
+
+## Updates to These Guidelines
+
+These guidelines will be reviewed and updated quarterly to reflect new AI capabilities, regulatory changes, and industry best practices. All team members are encouraged to contribute suggestions for improvements.
+
+> **Note:** The "Last Updated" date at the bottom of this document is automatically maintained by a GitHub Actions workflow whenever changes are pushed to this file. Please do not modify this date manually.
+
+Last Updated: May 11, 2025

.aiguidance/context-providers.json

@@ -0,0 +1,6 @@
+{
+  "currentFile": { "maxTokens": 20000 },
+  "diff": { "maxTokens": 10000 },
+  "terminal": { "maxLines": 1000 },
+  "folder": { "maxDepth": 4, "maxFiles": 30, "maxFileSize": 80000 }
+}