Function Taxonomy
Authoritative classification of every function in syntropy_journals/app/functions/ by scope.
This taxonomy drives MCP tool selection, API surface design, and refactoring priorities.
Updated: 2026-03-25 | PRD: PRD-20 (Consumer MCP)
Scope Definitions
| Scope | Code Location | Description | MCP Exposure |
|---|---|---|---|
| Internal | states/ (vars, ui_handlers) | UI state management, Reflex rendering, component logic | Never |
| User-Data | functions/db_utils/ | CRUD operations on user attributes, profile, settings | MCP Resources (read), MCP Tools (write) |
| User-Application | functions/diet/, functions/llm/, functions/checkins/ | Business logic workflows — scoring, analysis, AI chat | MCP Tools |
| Partner | functions/partner/, functions/db_utils/integration_analytics.py | Partner-scoped operations, adherence analytics | Separate Partner MCP |
| Consumer-Integration | functions/consumer/ | Shopify order sync, protocol extraction for end users | Internal (triggered by webhooks) |
| Infrastructure | functions/llm/middleware/, functions/llm/checkpoints/ | Agent middleware, checkpointers, embedding pipelines | Never (internal plumbing) |
Function Catalog
User-Data (Profile, Settings, Auth)
These functions read/write user attributes. Candidates for MCP Resources (read) and Tools (write).| Function | File | Operation | MCP Candidate |
|---|---|---|---|
get_user_profile_sync | db_utils/profile.py | Read user profile | get_health_profile resource |
get_health_profile_sync | db_utils/profile.py | Read health profile | get_health_profile resource |
update_user_profile_sync | db_utils/profile.py | Write user profile | Future: update_profile tool |
update_health_profile_sync | db_utils/profile.py | Write health profile | Future: update_health_profile tool |
get_user_profile_by_username_sync | db_utils/profile.py | Lookup by username | No (internal lookup) |
is_username_available_sync | db_utils/profile.py | Check availability | No (UI only) |
update_user_referral_source_sync | db_utils/auth.py | Write referral | No (onboarding only) |
get_user_protocols_sync | db_utils/protocols.py | Read subscribed protocols | get_my_protocols resource |
adopt_protocol_sync | db_utils/protocols.py | Subscribe to protocol | Future: subscribe_protocol tool |
update_user_protocol_sync | db_utils/protocols.py | Update subscription | No (UI-driven) |
get_chat_sessions_sync | db_utils/chat.py | Read chat sessions | get_my_chats resource |
get_or_create_chat_session_sync | db_utils/chat.py | Create chat session | Internal (via chat tool) |
delete_chat_session_sync | db_utils/chat.py | Delete chat session | No (destructive, UI only) |
User-Application (Diet Intelligence)
Business logic workflows. Primary MCP tool candidates.| Function | File | Operation | MCP Tool |
|---|---|---|---|
compute_diet_fulfillment_score | diet/scoring.py | Overall diet score | get_diet_score |
build_health_snapshot | diet/scoring.py | Aggregated health data | get_health_snapshot |
compute_ideal_diet_targets | diet/ideal_diet.py | Heuristic macro targets | get_diet_targets |
compute_diet_gap | diet/ideal_diet.py | Actual vs target comparison | get_diet_gap |
analyze_food_text | diet/agent.py | LLM food text extraction | analyze_food |
score_diet | diet/agent.py | Diet score wrapper | Via get_diet_score |
get_diet_recommendation | diet/agent.py | LLM diet recommendations | recommend_targets |
analyze_diet_gap | diet/agent.py | Gap analysis wrapper | Via get_diet_gap |
compute_dietary_sub_score | diet/alignment.py | Sub-score computation | Internal (part of alignment) |
compute_consistency_sub_score | diet/alignment.py | Sub-score computation | Internal (part of alignment) |
compute_checkin_sub_score | diet/alignment.py | Sub-score computation | Internal (part of alignment) |
compute_health_alignment | diet/alignment.py | Composite alignment score | get_health_alignment |
generate_score_insights | diet/insights.py | LLM score explanations | Part of get_health_snapshot |
get_personalized_targets | diet/profiler.py | LLM macro targets | recommend_targets |
User-Application (Health Entries & Check-ins)
Data entry operations. MCP write tools.| Function | File | Operation | MCP Tool |
|---|---|---|---|
create_food_log_sync | db_utils/health_entries.py | Log food entry | log_food |
get_food_logs_sync | db_utils/health_entries.py | Read food history | get_food_logs |
get_symptom_entries_sync | db_utils/health_entries.py | Read symptoms | Part of get_health_snapshot |
get_medication_entries_sync | db_utils/health_entries.py | Read medications | Part of get_health_snapshot |
get_macro_summary_sync | db_utils/health_entries.py | Macro totals | Internal (used by scoring) |
create_checkin_sync | db_utils/checkins.py | Create check-in record | log_checkin |
get_checkins_for_user_sync | db_utils/checkins.py | Read check-in history | get_my_checkins |
update_checkin_sync | db_utils/checkins.py | Update check-in | No (UI-driven edits) |
delete_checkin_sync | db_utils/checkins.py | Delete check-in | No (destructive) |
save_health_entries_sync | db_utils/checkins.py | Batch save entries | Internal (check-in processing) |
intake_and_process_checkin | checkins/intake.py | Full check-in pipeline | log_checkin (high-level) |
User-Application (AI Chat)
ShrineAI conversational interface. Core MCP tool.| Function | File | Operation | MCP Tool |
|---|---|---|---|
create_shrine_agent | llm/agent.py | Create agent instance | Internal (factory) |
get_compiled_graph | llm/agent.py | Get LangGraph agent | Internal (factory) |
get_chat_model | llm/client.py | Get LLM client | Internal (factory) |
extract_food_entries_llm | llm/extraction.py | LLM food extraction | Internal (via analyze_food) |
extract_notes_events_llm | llm/extraction.py | LLM event extraction | Internal (via check-in processing) |
get_relevant_context | llm/retrieval/scored_retriever.py | RAG context retrieval | Internal (agent middleware) |
Note: The MCP chat_with_shrine tool invokes the full agent pipeline (agent.py + middleware + retrieval). Individual LLM functions are internal plumbing, not exposed directly.
User-Application (Marketplace & Catalog)
Protocol browsing and scoring.| Function | File | Operation | MCP Tool |
|---|---|---|---|
get_catalog_protocols_sync | db_utils/catalog.py | Browse protocol catalog | browse_catalog resource |
get_catalog_categories_sync | db_utils/catalog.py | List categories | Part of browse_catalog |
compute_confidence_tier | marketplace/confidence.py | Protocol confidence score | Part of catalog enrichment |
check_safety | marketplace/safety.py | Safety check | Internal (always runs) |
Partner (Separate MCP)
Partner-scoped operations. NOT exposed in consumer MCP.| Function | File | Scope |
|---|---|---|
get_partner_protocols_sync | partner/db_utils.py | Partner portal |
get_adherence_data_sync | partner/db_utils.py | Partner analytics |
get_partner_metrics_sync | partner/db_utils.py | Partner dashboard |
calculate_pdc | partner/adherence.py | Adherence calculation |
calculate_streak | partner/adherence.py | Streak calculation |
generate_oauth_url | partner/shopify_oauth.py | Shopify OAuth |
exchange_code_for_token | partner/shopify_oauth.py | Shopify OAuth |
fetch_shopify_products | partner/shopify_products.py | Shopify sync |
get_partner_summary_sync | db_utils/integration_analytics.py | Partner analytics |
get_protocol_adherence_sync | db_utils/integration_analytics.py | Per-protocol stats |
get_protocol_feedback_sync | db_utils/integration_analytics.py | User feedback |
get_protocol_retention_sync | db_utils/integration_analytics.py | Retention funnel |
create_protocol_sync | db_utils/protocols.py | Protocol CRUD |
update_protocol_sync | db_utils/protocols.py | Protocol CRUD |
Consumer-Integration (Webhooks, Internal)
Triggered by external systems but not directly exposed via MCP.| Function | File | Scope |
|---|---|---|
fetch_customer_orders | consumer/shopify_orders.py | Shopify data pull |
extract_protocols_from_orders | consumer/protocol_extractor.py | Order → protocol extraction |
extract_events_from_checkin | consumer/event_extractor.py | Check-in → health events |
get_user_integrations_sync | consumer/db_utils.py | Integration status |
save_user_integration_sync | consumer/db_utils.py | Store integration records |
Infrastructure (Never Exposed)
| Function | File | Purpose |
|---|---|---|
build_middleware_stack | llm/agent.py | Agent middleware assembly |
get_checkpointer | llm/checkpoints/postgres_saver.py | LangGraph persistence |
get_thread_id | llm/checkpoints/thread_id.py | Thread ID generation |
create_summarization_middleware | llm/memory/summarization.py | Memory management |
get_embedding_model | llm/retrieval/embedding.py | Embedding pipeline |
create_vectorstore | llm/retrieval/vectorstore.py | Vector DB setup |
Refactoring Backlog
Processing logic that currently lives instates/ and should be extracted to functions/:
| State File | Issue | Target Location | Priority |
|---|---|---|---|
states/partner/adherence.py:136 | Inline rx.session() + adherence loop | functions/partner/adherence.py | High (blocks partner MCP) |
states/shared/clerk_auth.py:343 | Direct session query for profile | functions/db_utils/auth.py | Medium |
states/shared/mock_auth.py:101 | Direct session query | functions/db_utils/auth.py | Low (dev-only) |
states/base.py:41 | ConfigurableState session queries | Keep (intentional — admin config) | N/A |