jfarcand

Atmosphere Code Review — Issues Fixed

Two external reviews were conducted on the Atmosphere coordinator module and project documentation. This gist summarizes every issue found and how each was resolved.

---

Review 1: Agent/Fleet/Coordinator Architecture

Source: Architecture Review Gist

jfarcand

Atmosphere AI Framework Abstraction — Implementation Summary

Overview

Atmosphere's unified AI abstraction layer sits between @AiEndpoint handlers and the four supported AI frameworks (Spring AI, LangChain4j, Google ADK, Embabel). It provides:

• Tool Calling SPI — @AiTool annotation → framework-agnostic ToolDefinition → native bridges
• Capability Discovery — AiCapability enum + ModelRouter for smart routing/failover
• Conversation Memory — ConversationPersistence SPI backed by Redis or SQLite

jfarcand

Atmosphere AI Framework Abstraction Analysis

Overview

Atmosphere currently integrates with 4 external AI frameworks plus a built-in OpenAI-compatible client:

Framework	Module	Adapter	Request Type
Built-in OpenAI	modules/ai	BuiltInAiSupport	AiRequest
Spring AI	modules/spring-ai	SpringAiStreamingAdapter	ChatRequest

jfarcand

AI Provider Architecture: Two Separate Systems

1. MCP Sampling (Exploration — Active)

Used during generate_skill BFS/DFS exploration for component classification.

• Code: SamplingBridge.swift / SamplingClassifier
• How it works: Sends sampling/createMessage to the MCP client, which forwards it to whatever LLM the client is using (e.g. Claude via Claude Code)
• No API keys needed — the client's own LLM handles it
• Config: componentDetection in settings.json controls the mode:

jfarcand

Plan: Improve Component Calibration & Chevron Resilience

Context

Testing component detection on the Santé (Health) app reveals three problems:

1. Calibration is misleading — it shows per-row matches but not the post-absorption result. ChefFamille sees value rows ("Bouger", "893 cal") classified separately when in reality BFS absorbs them into the summary-card above. The calibration needs to show what BFS actually sees.
2. Calibration is viewport-only — only analyzes visible elements. ChefFamille wants full-page coverage via scrolling.
3. Distance card misses chevron — OCR inconsistently detects ">" next to "11:33" for one card while 3/4 similar cards get it. The hard row_has_chevron: true constraint causes hard failure.

SAM (Segment Anything Model) was considered for bounding-box detection but rejected — too heavy (50-500MB). The existing absorption mechanism (absorbs_below_within_pt: 80) already handles bounding-box suppression correctly; the calibration tool just doesn't show it.

jfarcand

Atmosphere 4 AI Features — Brainstorm

The key insight: Atmosphere's primitives (Broadcaster, BroadcasterCache, Interceptors, Rooms, Presence, Clustering) are proven patterns from 18 years of real-time work. No AI framework has equivalents because they all think model-out, not transport-out.

---

Tier 1 — Nobody else can do this

1. Multi-Model Fan-Out Streaming

jfarcand

Pierre Fitness Platform - Complete Technical Reference

This document is optimized for LLM consumption. Use it to answer questions about Pierre's architecture, code patterns, and implementation details.

---

OVERVIEW

Pierre is a production Rust fitness API platform implementing:

• MCP (Model Context Protocol) - JSON-RPC 2.0 protocol for AI assistant tool execution

jfarcand

Pierre MCP Server - Reference Part 4: Testing & CI

Reference documentation for ChatGPT. Part 4: Testing, CI/CD, Contributing.

---

Testing Guide

Pierre Fitness Platform includes comprehensive test coverage using synthetic data for intelligence tools.

jfarcand

Pierre MCP Server - Reference Part 3: Tools & Intelligence

Reference documentation for ChatGPT. Part 3: Tools, Sports Science, Nutrition.

---

MCP Tools Reference

Comprehensive reference for all 47 Model Context Protocol (MCP) tools provided by Pierre Fitness Platform. These tools enable AI assistants to access fitness data, analyze performance, manage configurations, and provide personalized recommendations.

jfarcand

Pierre MCP Server - Reference Part 2: Auth & Protocols

Reference documentation for ChatGPT. Part 2: Authentication, OAuth, Protocols.

---

Authentication

Pierre supports multiple authentication methods for different use cases.