MicroFish/.kiro/specs/i18n-oasis-profile-generator-prompts/gap-analysis.md

Gap Analysis — i18n-oasis-profile-generator-prompts

This document analyzes the gap between the requirements and the existing codebase, lists implementation options, and recommends an approach for the design phase.

1. Current State Investigation

Target file

backend/app/services/oasis_profile_generator.py — 1195 lines. Defines:

• OasisAgentProfile dataclass with Reddit / Twitter serializers.
• OasisProfileGenerator class with the following public-API surface: __init__, generate_profile_from_entity, generate_profiles_from_entities, set_graph_id, plus private helpers _call_llm_with_retry, _generate_profile_rule_based, _get_system_prompt, _build_individual_persona_prompt, _build_group_persona_prompt, _print_generated_profile, _fix_truncated_json, _try_fix_json, _save_twitter_csv, _save_reddit_json, _generate_username.

Chinese surfaces in the file (by category)

Category	Lines	In scope this issue?
Module / class / method docstrings	scattered	No — covered by #7
Inline # comments	scattered	No — covered by #7
logger.{info,warning,error} calls (translated via t("log.profile_generator.*"))	scattered	No — already done by #6
print(...) banners (e.g. line 945)	a few	No — companion to #6 in spirit; not a prompt literal
System prompt base_prompt (line 664)	1 line	Yes
Individual-persona prompt body (lines 680–714)	block	Yes
Group-persona prompt body (lines 729–762)	block	Yes
attrs_str / context_str defaults "无" / "无额外上下文" (lines 677, 678, 726, 727)	4 lines	Yes — they substitute into the prompt body
Rule-based fallback (_generate_profile_rule_based, lines 764–835) including "country": "中国" and "国家" placeholders	block	No — runtime data, not a prompt
Resilience-helper Chinese fragments (f"{entity_name}是一个{entity_type}。" at lines 547, 644, 659)	a few	No — runtime data, not a prompt

The file already imports get_locale, set_locale, t, and get_language_instruction from app.utils.locale. The locale-capture / restore plumbing inside generate_profiles_for_entities (lines ~910–916) already propagates the request locale to background-thread workers — no changes required.

Locale infrastructure (already in place)

backend/app/utils/locale.py:

• get_language_instruction() returns the per-locale postfix from /locales/languages.json (e.g. Please respond in English. for en, 请使用中文回答。 for zh).
• t(key, **kwargs) resolves log.* keys for backend logger messages; not used by this issue.
• set_locale / get_locale are thread-local, with restoration plumbed into generate_profiles_for_entities.

Sibling specs already shipped

• i18n-ontology-generator-prompts (#2 — merged)
• i18n-simulation-config-generator-prompts (#4 — merged)
• i18n-report-agent-prompts (#5 — merged)
• i18n-externalize-backend-logs (#6 — merged; logger keys for log.profile_generator.* are already in locales/{en,zh}.json)

The translation pattern they established:

1. Translate the base prompt body (English narrative + headings).
2. Preserve every get_language_instruction() call site verbatim so Accept-Language: zh still produces Chinese output.
3. Preserve all {variable} interpolations in f-strings.
4. Preserve all locale-independent "lock" rules (e.g. gender enum) in English text within the prompt.
5. No new dependencies, no new files, single-file diff.

This is a direct sibling — same pattern applies.

Test contract

backend/scripts/test_profile_format.py:

• Pytest-collectable function test_profile_formats.
• Constructs OasisAgentProfile instances directly (no LLM call) and serializes them via _save_twitter_csv / _save_reddit_json.
• Verifies CSV header includes user_id, user_name, name, bio, friend_count, follower_count, statuses_count, created_at and JSON output includes realname, username, bio, persona.
• Does not exercise the prompts. A pure prompt translation cannot break it; a refactor of dataclass field names or serializers would.

Callers

• backend/app/services/simulation_manager.py:316 — OasisProfileGenerator(graph_id=state.graph_id).
• backend/app/api/simulation.py:1413 — OasisProfileGenerator().

Neither caller looks at prompt language; both consume the persona dict output. No call-site changes are needed.

2. Requirement-to-Asset Map

Req.	Asset / file	Gap
1. System prompt → English	_get_system_prompt line 664	Missing — Chinese literal needs to become English literal
2. Individual-persona template → English	_build_individual_persona_prompt lines 680–714	Missing — Chinese block needs translation; preserve {...} interpolations and inline {get_language_instruction()}
3. Group-persona template → English	_build_group_persona_prompt lines 729–762	Missing — Chinese block needs translation; preserve {...} interpolations and inline {get_language_instruction()}
4. Locale switching unchanged	app.utils.locale + the three get_language_instruction() call sites	Constraint — code path must stay byte-identical at those call sites
5. Public API stability	OasisAgentProfile dataclass + OasisProfileGenerator method signatures	Constraint — no signatures change
6. Reasoning-model parsing unchanged	_fix_truncated_json, _try_fix_json	Constraint — no edits
7. OASIS schema parity	_save_twitter_csv, _save_reddit_json, to_*_format serializers	Constraint — no edits; pytest must continue passing
8. Out-of-scope guard	logger calls, docstrings, comments, rule-based fallback	Constraint — explicitly do not edit

No requirement is blocked or unknown. Every requirement maps to a known location with a clear, narrow change.

3. Implementation Approach Options

Option A — In-place edit of the three prompt builders (extend existing)

Translate base_prompt (1 line), the individual-persona f-string body (~35 lines), and the group-persona f-string body (~34 lines) directly, plus the four "无" / "无额外上下文" fallback literals. Keep all method bodies otherwise byte-identical.

• Files touched: backend/app/services/oasis_profile_generator.py only.
• Compatibility: zero API change. All call sites unaffected. Locale switching preserved by leaving the inline {get_language_instruction()} placeholders untouched.
• Complexity: low. Pattern is identical to merged siblings #2, #4, #5.

Trade-offs:

• ✅ Minimal diff, exactly the pattern reviewers expect.
• ✅ No risk to the unrelated rule-based fallback or serialization paths.
• ✅ Out-of-scope items (logger, docstrings, rule-based fallback) are not touched, so #6/#7 remain clean.
• ❌ Leaves the file mixed-language in non-prompt parts (docstrings, rule fallback) until #7 lands. Acceptable per scope split.

Option B — Move prompt strings into module-level constants

Introduce INDIVIDUAL_PERSONA_PROMPT_TEMPLATE and GROUP_PERSONA_PROMPT_TEMPLATE constants at module scope (mirroring ONTOLOGY_SYSTEM_PROMPT style in ontology_generator.py), and have the builders .format(**kwargs) against them.

• Files touched: same single file, but with structural refactor.
• Compatibility: still zero public API change, but the diff is larger and reviewers must verify equivalent behaviour around {get_language_instruction()} (which would need to become a runtime substitution not an f-string interpolation, since constants don't re-evaluate per call).

Trade-offs:

• ✅ Constants are easier to spot in git grep.
• ❌ Larger diff, more review surface.
• ❌ The inline get_language_instruction() call is currently captured at f-string render time; moving to a .format(...) template requires passing the resolved instruction in as a kwarg — a behavioural change that exceeds "translate prompts only".
• ❌ Diverges from the sibling pattern just shipped (#4, #5 used in-place edits, not module constants). #2 used module constants but only for the system prompt — the user-message template was still built inside the method.

Option C — Externalize prompt text into /locales/*.json

Move every prompt sentence into locales/en.json and locales/zh.json, keyed under prompt.profile_generator.*, and use t(key, **vars) to resolve.

• Compatibility: would address Accept-Language purely via the existing translation mechanism without depending on the get_language_instruction() postfix.

Trade-offs:

• ✅ Most i18n-pure approach.
• ❌ Significantly larger diff (touches three repos: source file, en.json, zh.json).
• ❌ Diverges from the established project pattern. The sibling specs (#2, #4, #5) deliberately did not externalize prompts — the project rationale (per tech.md) is that backend logger messages are the i18n surface, while LLM prompts use the get_language_instruction() postfix mechanism.
• ❌ Higher review and merge cost for no operational gain.

4. Recommended Approach

Option A — single-file in-place edit of the three prompt builders plus the four "无" / "无额外上下文" fallback literals.

Rationale:

• Matches the merged sibling specs verbatim (#2, #4, #5) so reviewers can apply the same mental checklist.
• Smallest possible diff that satisfies every acceptance criterion in requirements.md.
• Leaves out-of-scope surfaces (logger, docstrings, rule-based fallback) untouched — clean handoff to #7 and clean separation from already-merged #6.
• Zero new dependencies, zero new files, zero API change, zero risk to test_profile_format.py.

Translation choices to lock in during design

1. The system prompt base_prompt becomes a single English sentence in the spirit of the original (expert in social-media persona generation; detailed and realistic personas for opinion simulation; faithful reflection of real-world conditions; valid JSON, no unescaped newlines).
2. The two persona prompt bodies adopt English section headings and prose. The previously-Chinese hint country: 国家（使用中文，如"中国"） is dropped — the get_language_instruction() postfix already steers locale, and the rule-based fallback (out of scope) handles its own country values.
3. The trailing rules block keeps the locale-independent "lock" constraints inline (gender enum, age integer requirement, persona newline rule) and continues to embed {get_language_instruction()} verbatim.

5. Effort & Risk

• Effort: S (1–3 days; realistically <½ day). One-file diff, established sibling pattern, no new test infrastructure.
• Risk: Low. The translated prompts touch only the LLM messages payload. The locale-switching pathway, public API, serializers, retry logic, fallback, and tests are all untouched. The only failure mode is a mistranslated constraint (e.g. accidentally dropping gender ∈ {male, female, other}), which the design checklist enumerates and reviewers can verify by diff.

Research items carried into design phase

• None blocking. The design phase will:
  • Enumerate the exact final English text for each of the three blocks.
  • Verify each translated block preserves every JSON-output key, every {variable} interpolation, and the inline {get_language_instruction()} call.
  • Spot-check that the diff stays within backend/app/services/oasis_profile_generator.py.