Framework Roadmap

This roadmap focuses on making Silisocs a powerful simulator and extensible framework without losing the current YAML-first workflow.

Target Architecture

Silisocs should make each simulator layer replaceable through a defined shape:

Layer	Stable shape	Extension path
Scenario	Hydra config groups plus scenario-local overrides	Add scenario files, agent variants, study overrides
Agent	Agent runtime plus optional compatibility adapter	Custom agent module or custom builder
Environment app	BackendApp plus @app_action methods	Built-in env.gm.backend.type or env.gm.backend.class_path
Timeline/recsys capability	SocialBackendApp optional timeline/recsys interface	Twitter-like, Reddit-like, Mastodon, or custom backend using those components
GM	Component-slotted game master	Override component slots before replacing the full GM
GM component	Slot config with built_in, class_path, params, optional flows	Custom initialize, next-acting, action_prompt, observe, resolve, update
Engine	Runtime loop plus policy objects	Custom turn-policy or probe-schedule policy first; custom engine only when needed
Evaluation	Probe deployment plus postprocessors/evaluators	Custom probe types and study evaluators

V1 Priorities

1. Documentation completeness
2. Keep Documentation Coverage current.
3. Make Backends the canonical guide for generic and social backend authors.

4. Make Simulation Extensibility API the canonical contract reference for agents, apps, GMs, components, engines, and policies.

5. Strict config contracts

6. Treat YAML params as public constructor arguments.
7. Fail fast on unknown params unless the target class accepts **kwargs.

8. Apply this consistently to GM components, engine policies, and custom environment apps.

9. Generic simulator boundary

10. Keep BackendApp domain-neutral.
11. Keep timeline/recommendation assumptions inside SocialBackendApp, social observe components, social resolve components, and recommendation components.

12. Use resource_market and virtual_space as small reference-world backends.

13. Contract tests

14. Test each extension shape with one small custom implementation.
15. Include negative tests for bad config keys, unknown actions, and missing required app methods.

16. Keep fast non-LLM smoke tests for packaged sample worlds.

17. Configuration discoverability

18. Document env.gm.backend.class_path and env.gm.backend.params.
19. Document component slot params and flows.
20. Add generated or checked config tables once the schema settles.

Feature Backlog

Priority	Feature	Why it matters
P0	Strict constructor validation for extension params	Prevents silent YAML typos and broken custom components
P0	Reference-world backend docs and samples	Proves Silisocs is a simulator framework, not only social media
P1	Capability matrix for backends	Makes optional timeline/recsys/live-server features explicit
P1	Public/internal API labels	Helps extension authors avoid unstable modules
P1	Typed config schema or generated config reference	Reduces drift between YAML defaults and docs
P1	Plugin-style discovery for backends/components	Avoids editing core factories for every extension
P2	Deterministic replay harness	Improves experiment auditability and regression tests
P2	Benchmark world suite	Tracks runtime, cost, scale, and behavioral regressions
P2	Rich evaluator registry	Makes study analysis as configurable as simulation setup
P2	Distributed/batched execution	Enables larger experiment grids without custom orchestration

Acceptance Markers

The framework is in good V1 shape when:

• A new backend can be added through env.gm.backend.class_path without changing core runtime code.
• A new GM component or engine policy can be configured with documented params, and typos fail before simulation starts.
• Public docs describe every stable extension surface.
• Reference-world smoke tests run without timeline or recommendation assumptions.
• uv run pytest and uv run --group docs properdocs build --strict pass in the contributor environment.