ysimulator_alignment.md

YPhotoSharing vs YSimulator Alignment Analysis

Scope

This document compares the current YPhotoSharing implementation with the YSimulator reference project, focusing on:

• module and submodule organization
• implemented facilities and gaps
• the differences caused by the two engines targeting different platforms
• a phased plan to align YPhotoSharing where it makes architectural sense

YSimulator is a microblogging simulator centered on text posts, threaded replies, feed/news mechanics, and opinion dynamics over short-form content. YPhotoSharing is an Instagram-like simulator centered on visual posts, photo generation, comments on media, stories, saved content, and media-centric attention dynamics.

The goal is not to clone YSimulator mechanically. The right target is to adopt the same engineering discipline, layering, and observability while keeping the product semantics photo-first.

---

Executive Summary

YPhotoSharing already implements a useful subset of the YSimulator shape:

• Ray-based split between client and server
• centralized server-side database ownership
• LLM-backed agent actions
• feed/recommendation services
• interests, opinions, moderation, virality, analytics, and media generation

However, compared with YSimulator, the current project is still less modular and has a few intentionally open refactoring seams:

• the server layer still acts as a large façade over the DB middleware
• several DB helpers are still concentrated in db_middleware.py instead of being split into repository-style components
• logging now emits structured execution, actor, request, usage, action, and prompt records from the Ray actors
• the advanced stress/reward mechanic is integrated across the supported social-feedback paths, but it remains more distributed than in YSimulator
• topic propagation is now persisted, but the surrounding service structure is still less layered than YSimulator's
• some YSimulator facilities were translated conceptually, while others were intentionally not ported because they are microblogging-specific

In short:

• YSimulator is a more mature, highly modular microblogging engine
• YPhotoSharing is a smaller photo-sharing engine with some duplicated patterns, some legacy compatibility code, and fewer extraction layers

---

High-Level Comparison

YSimulator

YSimulator is organized as a large but highly decomposed simulation platform:

• YServer
  • action_processors
  • recommendation
  • repositories
  • services
  • coordination
  • opinion_dynamics
  • interests_modeling
  • classes
• YClient
  • action_generators
  • simulation
  • llm_utils
  • opinion
  • stress_reward
  • news_feeds
  • memory_runtime
  • recsys
  • agent_management

This organization reflects a deliberate separation:

• action generation is isolated from simulation orchestration
• server-side request processing is split into action processors
• domain services are isolated from storage
• client-side behavior is decomposed into generators, schedulers, and helpers

YPhotoSharing

YPhotoSharing is much flatter:

• YServer
  • server.py
  • classes/
  • services/
  • recsys/
  • coordination/
  • interests_modeling/
  • opinion_dynamics/
• YClient
  • client.py
  • agent_management/
  • actions/
  • LLM_interactions/
  • opinion/
  • stress_reward/

The implementation is workable, but the boundaries are less strict:

• the server still exposes many direct façade methods
• DB logic remains concentrated in db_middleware.py
• client behavior is mostly action-oriented, not generator-orchestrator split
• some features are implemented in the action functions themselves rather than in dedicated domain processors or services

---

What YPhotoSharing Already Has

Core Platform

• Ray-based SimulationClient and OrchestratorServer
• SQLite-backed SQLAlchemy persistence
• user creation and profile loading
• follow/unfollow, private follow requests, DMs, save/bookmark, report
• photos, comments, reactions, stories, and media storage
• recommendation feeds and ranking
• moderation, virality, analytics, and influence metrics

Content and Semantics

• photo generation through ImageGenerationService
• vision model integration for multimodal generation and interpretation
• topic/interest modeling
• opinion dynamics for content interactions
• memory events for interaction history
• optional sentiment extraction

Advanced Dynamics

• finite attention budget
• satisfaction/churn logic
• interest evolution from interactions
• stress/reward dynamics
• logging support with rotating file handlers

---

What YSimulator Has That YPhotoSharing Does Not Yet Mirror

1. Deeper server decomposition

YSimulator has a more explicit split between:

• request routing
• action processing
• repositories
• services
• coordination
• recommendation policies

YPhotoSharing still relies on:

• a large OrchestratorServer
• a broad DatabaseMiddleware
• a mix of domain-specific services and direct DB methods

This is acceptable for a smaller project, but it creates maintenance pressure as the feature set grows.

2. Stronger client-side orchestration separation

YSimulator separates:

• action generation
• scheduling
• round execution
• lifecycle management
• batch processing

YPhotoSharing mostly keeps orchestration inside SimulationClient and action functions. That is easier to follow initially, but harder to scale cleanly.

3. Better separation of opinion and interest mechanics

YSimulator has a very explicit opinion and stress/reward pipeline:

• client computes variations
• server persists aggregate and variation rows
• client and server both agree on the temporal model

YPhotoSharing now mirrors the core of that behavior for photo-centric interactions, but some differences remain:

• photo topics must stay a first-class link at creation time and when photos are used in comments, reactions, replies, and shares
• topic identifiers and topic names must not drift apart in future code paths
• stress/reward is present, but it is still implemented as a set of action hooks rather than a dedicated policy layer
• some YSimulator action families do not have an Instagram-like equivalent, so parity should be judged only on the supported photo-sharing paths

4. More complete observability pattern

YSimulator treats logging as a first-class runtime concern:

• actor logs
• action logs
• prompt logs
• request logs
• structured records

YPhotoSharing now emits structured execution logs, actor logs, server request traces, and LLM usage traces, while still supporting optional action and prompt logs when enabled.

---

What YPhotoSharing Should Not Copy Directly

Because the goals differ, some YSimulator facilities should remain absent or be reinterpreted rather than copied:

• news_feeds and article ingestion are microblogging-specific and should not become a first-class YPhotoSharing dependency
• reply_handler and text-first generation flows should not replace media-first actions
• search, cast, or news article recommendation abstractions should only be ported if a photo-sharing equivalent is needed
• a direct post / tweet terminology clone would be semantically wrong for the photo platform

The photo platform equivalent of a microblog post is a media post with:

• generated image
• caption
• optional filter and location
• topic tags
• social annotations

---

Current Gaps and Issues

A. Data model and persistence gaps

Observed issues:

• photo_topics must stay populated at photo creation time and remain available when the photo is later commented on, reacted to, shared, or replied to
• topic IDs and topic names should remain stable and not drift apart in future call paths
• a few helpers still live inside db_middleware.py where YSimulator would use a repository-style split
• missing lookups should continue to return None instead of sentinel values

What this means:

• interest evolution can drift or silently fail
• opinion dynamics can miss cold-start conditions
• cross-feature analytics become inaccurate

B. Logging gaps

Observed issues:

• execution logs, actor logs, request traces, and LLM usage traces are now populated from inside the Ray actors
• the remaining parity gap is breadth: YSimulator also keeps separate action logs and prompt logs
• a future parity step should keep those secondary log streams only if they are genuinely useful for YPhotoSharing debugging and analysis

What this means:

• runtime debugging is better than before, but still not as rich as YSimulator
• post-hoc analysis remains centered on execution logs rather than per-action traces

C. Stress/reward integration gaps

Observed issues:

• the stress/reward module is now wired into the supported social-feedback flows, but the implementation is still distributed across action handlers
• comment, reaction, share, report, and reply-comment paths are covered
• server-side aggregate state and variation rows are present, but this area still deserves regression coverage because it directly affects churn

What this means:

• churn and reward feedback loops are functionally present
• the main remaining work is tightening the architecture and the tests around them

D. Architectural gaps versus YSimulator

Observed issues:

• YServer is still a broad façade rather than a strongly layered service entrypoint
• YClient keeps orchestration inside the actor rather than a richer action-generator / scheduler split
• there is still no full equivalent of YSimulator’s request processor and repository layers
• the existing repositories/ package is effectively a placeholder

What this means:

• the codebase is usable, but future growth will increase coupling
• adding new actions or domain mechanics still requires touching multiple layers

---

Alignment Strategy

The right approach is selective alignment:

1. Keep the photo-sharing semantics.
2. Borrow the layering and separation patterns that improve maintainability.
3. Avoid porting microblog-specific concepts that do not fit Instagram-like behavior.

The alignment target should be:

• same quality of modularity as YSimulator
• same level of observability
• same strength of testability
• photo-native domain concepts

---

Proposed Phased Plan

Phase 1: Observability Completion

Goal: decide whether YPhotoSharing should add YSimulator-like secondary logs.

Status: implemented.

Tasks:

• keep the current structured execution logs and gzip rotation
• add a dedicated action log stream only if per-round action tracing is useful
• add a dedicated prompt log stream only if prompt auditing materially helps
• document the exact filename and record structure for the logs that remain

Success criteria:

• execution logs remain populated from inside the Ray actors
• any added secondary log streams serve a concrete photo-sharing need

Phase 2: Correctness and Schema Parity

Goal: keep the data model internally consistent.

Status: implemented.

Tasks:

• normalize photo topic persistence end to end
• standardize topic name vs topic ID usage
• ensure missing lookups return None instead of fake default values
• remove or isolate placeholder/stub database helpers
• ensure photo_topics, user_interest, user_opinion, and stress_reward are all written through the same temporal conventions

Success criteria:

• photos always store one or more topic associations
• comments, reactions, and shares can recover topics from the photo
• opinion dynamics do not confuse missing data with neutral state

Phase 3: Domain Decomposition

Goal: introduce YSimulator-style internal structure without changing semantics.

Status: partially implemented. The current codebase already has a service layer and client-side orchestration split, but the repository split remains a future refactor rather than a hard requirement.

Tasks:

• split the server façade into smaller services if needed
• separate request handling from domain persistence
• extract action processing for photo, comment, reaction, share, report, and DM
• isolate feed/recommendation policy concerns from DB writes
• move reusable cross-cutting logic out of action helpers
• consider a real repository layer if db_middleware.py keeps growing

Possible target structure:

• YServer/action_processors
• YServer/repositories
• YServer/services
• YClient/action_generators
• YClient/simulation

Success criteria:

• new actions can be added with less code duplication
• server logic becomes easier to test in isolation

Phase 4: Affective Dynamics Hardening

Goal: keep stress/reward and opinion behavior correct under refactor.

Status: implemented.

Tasks:

• preserve YSimulator-style stress/reward configuration
• compute deltas for reactions, comments, shares, reports, and reply comments
• persist variation rows and aggregate state on the server
• make churn decisions depend on the current stress/reward state
• keep bounded-confidence and Likert-style opinion updates in sync with the persisted path tables

Success criteria:

• affective state updates are written for all supported social interactions
• server queries can reconstruct current stress/reward state by round

Phase 5: Client Behavior Modularization

Goal: move toward YSimulator’s client organization where it helps.

Status: implemented.

Tasks:

• extract round orchestration from SimulationClient
• split population loading, scheduling, and action execution
• create dedicated generators or processors per action family if useful
• keep opinion/stress reward preparation as reusable helpers

Success criteria:

• SimulationClient becomes a coordinator, not a dumping ground
• actions become easier to test and reuse

Phase 6: Advanced Platform Mechanics

Goal: deepen the Instagram-like differentiation.

Status: intentionally deferred unless new product requirements need it.

Tasks:

• improve story mechanics
• refine photo generation and media annotations
• expand media-aware ranking and discovery
• consider richer visual topic extraction if it materially helps interest dynamics
• model creator economy pressure and retention more explicitly

Success criteria:

• photo-first interactions feel more distinct from microblogging
• the simulation captures visual-content network effects

Phase 7: Parity Tests and Regression Coverage

Goal: lock in behavior before deeper refactors.

Status: implemented.

Tasks:

• add integration tests for photo topic propagation
• add tests for stress/reward persistence and aggregation
• add tests for actor-side logging output
• add tests for any new action/prompt log streams
• add tests for direct comment/reaction/share/report interest updates
• add regression tests for null vs neutral opinion handling

Success criteria:

• refactors can proceed without reintroducing silent data loss
• the current feature set remains stable while the architecture evolves

---

Recommended Priorities

If implementation capacity is limited, the order should be:

1. Correctness and schema parity
2. Server/client decomposition
3. Stress/reward and opinion hardening
4. Optional extra logging streams
5. Regression testing
6. Additional Instagram-native depth

That ordering minimizes the risk of building new features on top of unstable foundations.

---

Practical Mapping

YSimulator concept -> YPhotoSharing equivalent

YSimulator	YPhotoSharing
post	photo post with caption and media
reply	comment reply on a photo thread
news/article	not first-class; optionally external content or creator-inspired media
cast/search	not generally applicable
topic	interest / content topic on a photo
content recsys	home/explore ranking over photos
follow recsys	people suggestions
memory runtime	interaction memory events and social cards
stress_reward	same concept, but tied to photo interactions and creator feedback
action generators	agent action helpers, future extraction target
simulation orchestrator	SimulationClient and round management

What should stay distinct

YPhotoSharing should emphasize:

• visual content generation
• photo topic inference
• story and ephemeral media behavior
• bookmarks/saves and DMs
• creator-facing feedback loops

It should not be forced into a microblogging shape just for parity.

---

Conclusion

YPhotoSharing is structurally inspired by YSimulator, but it is not yet at the same maturity level in decomposition and runtime consistency.

The best path forward is:

• preserve the Instagram-like domain model
• adopt YSimulator’s layering discipline selectively
• finish the currently incomplete facilities
• add tests before deeper refactors

That gives you a platform that is both semantically correct for photos and maintainable at YSimulator-like quality.

For the concrete implementation backlog, see docs/remaining_gaps.md.