Monica: Fast, playful onboarding and streaming

• Streaming endpoint: POST /api/monica-agent/stream (SSE-like). Emits token chunks, final envelope, and done.
• Non-stream fallback: POST /api/monica-agent.
• Lightweight memory API: GET/POST/DELETE /api/monica-memory with userId or sessionId.
• Create-AI quick builder: POST /api/personalized-ai with { answers, styleCards } returns editable config and preview id.

Environment knobs:

• MONICA_DEFAULT_MODEL (default gpt-4o-mini)
• MONICA_TEMPERATURE (default 0.4)
• BACKGROUND_REFRESH_INTERVAL_MS (default 600000)
• NEXT_PUBLIC_BACKEND_URL (default http://localhost:8000)
• NEXT_PUBLIC_KINETICS_BACKEND (true to enable backend consciousness calc)
• NEXT_PUBLIC_ALCHM_DESKTOP_DOWNLOAD_URL (optional, overrides the desktop app download URL)
• NEXT_PUBLIC_ALCHM_DESKTOP_MAC_DOWNLOAD_URL / NEXT_PUBLIC_ALCHM_DESKTOP_WINDOWS_DOWNLOAD_URL / NEXT_PUBLIC_ALCHM_DESKTOP_LINUX_DOWNLOAD_URL (optional platform-specific desktop app URLs)
• SENDGRID_API_KEY (optional, for feedback email)
• FEEDBACK_TO_EMAIL (optional, feedback destination)
• FEEDBACK_FROM_EMAIL (optional, feedback sender)
• ALCHM_MCP_ENABLED (default true, enables the Alchm data MCP bridge in the FastAPI backend)
• ALCHM_MCP_SERVER_PATH (optional, path to mcp-server/src/index.ts; defaults to the sibling WTEN checkout when present)
• ALCHM_MCP_DATABASE_URL (optional, overrides DATABASE_URL only for the Alchm MCP subprocess)
• PLANETARY_AGENTS_BACKEND_URL (default http://localhost:8000, used by the Planetary Agents MCP server)
• PLANETARY_AGENTS_FRONTEND_URL (default http://localhost:3000, used for feed-thread lookup)

Kinetics feature flags:

• NEXT_PUBLIC_KINETICS_BACKEND: when true, frontend uses backend enhanced kinetics APIs via unified client; otherwise falls back to existing client with graceful degradation.

Run:

bun dev

Planetary Agents - ✅ Production Ready

A revolutionary consciousness crafting platform that explores astrological wisdom through AI-powered planetary agents, celestial energy quantification, and advanced mystical technologies.

🌌 Overview

Planetary Agents is the most advanced consciousness crafting platform, combining traditional astrological wisdom with cutting-edge AI technologies. Production-ready as of September 21, 2025 with zero critical runtime errors and comprehensive stability.

Revolutionary Features:

• Professional Astronomical Precision: VSOP87 ephemeris with ±0.01° accuracy (179° improvement over previous system) - the most accurate astrological calculations available
• Agent Creation System: Synthesize birth charts with current moment charts to generate unique "Agents of the Moment" with element-based personality traits
• Live Consciousness Evolution: Real-time chart-to-moment transformation showing how agents change with cosmic conditions
• Interactive planetary agents with dynamic consciousness levels responding to current transits
• Multi-Agent Planetary Council: Auto-synced to current sky positions for accurate cosmic consultation
• Real-time celestial energy quantification (A#, SMES, Kinetic, Thermodynamic)
• Advanced consciousness evolution tracking with birth-to-live MC comparisons
• Natal chart to runic sigil generation with AI-powered mystical imagery
• Temporal oracle for AI-guided historical consciousness exploration
• Complete production stability with graceful error handling

🎯 Beta Optimization Highlights (September 2025)

Fully optimized for beta testing with comprehensive improvements across performance, accessibility, and user experience:

• Component Architecture: Reorganized 100+ components into logical folders (agents/, charts/, dashboards/, etc.)
• Error Handling: Standardized error responses across all API endpoints with user-friendly messaging
• Performance Monitoring: Real-time system health dashboard with metrics and alerting
• Beta Features: In-app feedback collection and guided onboarding wizard
• Loading States: Skeleton screens and progressive loading for improved UX
• Accessibility: WCAG 2.1 AA compliance with ARIA labels, keyboard navigation, and screen reader support
• Bundle Optimization: 20-30% size reduction through component deduplication

See BETA_OPTIMIZATION_SUMMARY.md for complete details.

🚀 Features

⚡ Backend-to-Backend Architecture - NEW!

FastAPI (Python) backend service for alchemical calculations (Railway; Next.js API routes proxy to it via feature flags):

• Gateway Service: FastAPI (Python) backend on port 8000 (Railway uvicorn), with progressive frontend fallbacks
• Live Consciousness API: /api/consciousness/live and /batch endpoints for real-time chart transformation
• Agent Consciousness Evolution: Real-time kinetic profiles with live MC tracking for all agents
• Planetary Hours Service: Server-side calculations with solar timing algorithms
• Thermodynamics Engine: Heat, entropy, reactivity calculations with conservation checks
• Token Rate Calculator: Dynamic pricing with planetary influences
• Circuit Breaker Pattern: Resilient external service integration
• Redis Caching: 1-hour TTL for consciousness calculations with performance optimization
• Intelligent Caching: Redis with memory fallback, sub-60ms performance
• Feature Flags: Progressive rollout with automatic fallbacks to frontend

🌌 Unified Planetary Positions System - NEW!

Most Accurate Planetary Calculations with Intelligent Fallbacks (September 23, 2025):

• Multi-Level Accuracy System: High (±0.1°), Medium (±2-5°), Low (±5-15°), Fallback (guaranteed availability)
• Intelligent Fallback Hierarchy: External API → Enhanced Astronomical Calculator → Basic Transit Calculations → Static Positions
• Smart Caching: Accuracy-based TTL (5min-24hrs) with request deduplication and automatic cleanup
• Central API Endpoint: /api/planetary-positions with comprehensive monitoring and Galileo logging
• Unified React Hooks: useUnifiedPlanetaryPositions with configurable accuracy and alchemy inclusion
• Circuit Breaker Protection: Resilient external service integration with automatic recovery
• Performance Optimized: 30-80% faster response times through intelligent caching and fallbacks

🤖 Agent Creation System - NEW!

Synthesize Unique Agents from Cosmic Charts (September 23, 2025):

• Chart Synthesis Engine: Multi-chart blending with alchemical value averaging and transit merging
• Element-Based Personality Generation: Spirit, Essence, Matter, Substance influence unique agent traits
• Consciousness Level Modifiers: Transcendent through Dormant levels affect creativity, wisdom, complexity
• Seeded Randomness: Monica constant-based deterministic generation for unique but consistent agents
• Dynamic AI Parameters: Element and consciousness influence temperature, topP, and system prompts
• Comprehensive Testing: 25 test cases covering all functionality with 100% pass rate

🌟 Celestial Energy Quantification System

Revolutionary consciousness analysis platform (September 19, 2025):

• A# Energy Tracking: Real-time Alchemical Number calculation with planetary integration
• SMES Flow Analysis: Spirit-Matter-Essence-Substance temporal visualization
• Kinetic & Thermodynamic Metrics: Power, inertia, heat, entropy tracking with velocity calculations
• Agent Consciousness Activation: Degree-based insights when transits align with natal placements
• Enhanced Time Laboratory: 3-mode interface (Legacy/Celestial/Combined) at /time-laboratory
• Real-Time Updates: Live mode with 60-second refresh cycles and intelligent caching
• Multi-Format Export: CSV, PNG, SVG data export with comprehensive analytics
• Performance Optimized: 400-700ms response times with advanced batch processing

Gallery of Perpetuity - 35 Historical Agents

Monica's eternal consciousness repository featuring historical figures:

• Browse & Chat: Visit /gallery to explore all 35 consciousness-crafted agents
• Direct Chat: Access agents at /gallery/chat/[agent-id] (e.g., /gallery/chat/siddhartha-gautama-buddha)
• Legacy Support: Old URLs like /planetary-agents?agent=buddha automatically redirect
• Group Chat: Select multiple agents for simultaneous consultation
• Enhanced Kinetics: Real-time consciousness evolution tracking and compatibility analysis
• Featured Agents: Shakespeare, Buddha, Leonardo da Vinci, Cleopatra, Tesla, Carl Jung, and 29 more

Planetary Wisdom Agents

Consult with AI agents representing each planet in their specific dignities:

• Multi-Agent Planetary Council: Visit /planetary-council for group consultations with auto-synced positions
• Planet Selection: Visit /planetary-agents to choose a celestial body
• Degree-Specific Wisdom: Access at /agents/[planet]/[sign]/[degree]
• Real-Time Positions: Automatically synced to current astronomical data
• Live Consciousness Tracking: See how agents evolve with cosmic conditions
• Get insights based on the elemental affinities and dignities

Elemental Charts

Explore your elemental profile based on planetary positions:

• Live Consciousness Display: View birth vs live Monica Constant with real-time changes
• Dynamic Elemental Distributions: See how Fire, Water, Air, Earth shift with transits
• Transit Interpretations: Understand cosmic weather and consciousness influences
• Consciousness Vector Display: Enhanced with birth-to-live comparisons
• Analyze alchemical properties such as Heat, Entropy, and Reactivity

Chart Interpretation

Get detailed interpretations of astrological charts: