Graphiti's default cross-encoder hard-codes the OpenAI gpt-4.1-nano model
and depends on OpenAI-specific logprobs/logit_bias, so the adapter has
been injecting a no-op _PassthroughReranker just to keep search code
paths working. Search results consumed by SearchResult, InsightForge,
Panorama, and Interview were therefore returned in Graphiti's RRF order
with no real reranking signal.
Add an Ollama-backed CrossEncoderClient that scores passages through a
local chat model via the OpenAI-compatible /v1 surface and wire it into
_get_graphiti() behind a RERANKER_PROVIDER switch (default: ollama).
Construction is side-effect-free and the rank() method never raises:
per-passage parse failures degrade to a deterministic low score, and a
whole-call failure falls back to passthrough order with a single WARNING
log so Flask keeps serving when Ollama is unreachable. Setting
RERANKER_PROVIDER=none preserves the legacy passthrough for CI and slim
containers that cannot pull the model.
Closes#39
Two coupled changes that together restore non-empty post-migration graph
builds and remove the silent "succeeded but empty" outcome.
Root cause: Config defaulted EMBEDDING_MODEL to OpenAI text-embedding-3-small
(1536 dim), but Graphiti's Neo4j vector index is 1024 dim. With the
documented Dashscope LLM default, EMBEDDING_API_KEY/EMBEDDING_BASE_URL
fell back to LLM_*, producing either a 4xx (since #29 propagates as
Task.FAILED) or a write that landed metadata but no entities.
Changes:
- Flip Config defaults to local Ollama (mxbai-embed-large, 1024 dim,
http://localhost:11434/v1). Override semantics unchanged: explicit
EMBEDDING_* env vars continue to win, so existing OpenAI/Gemini setups
are not affected.
- Gate _build_graph_worker on a non-zero entity-node count before
complete_task. Mirrors the existing _recover_stuck_projects rule;
surfaces any residual silent failure as Task.FAILED with the new
progress.emptyGraphFailure locale key, instead of marking the project
GRAPH_COMPLETED on an empty graph.
- Update README, CLAUDE.md, and docker-compose.yml comments to reflect
Ollama as the active default and OpenAI/Gemini as commented fallbacks.
- The matching .env.example diff is recorded in
.kiro/specs/graph-build-empty-fix/HANDOFF.md for manual operator apply
(file is hook-protected from the assistant).
Spec: .kiro/specs/graph-build-empty-fix/
Closes#37
backend/app baseline drops from 2792 to 307 after the comment/docstring
translation pass. Mark i18n-translate-backend-comments tasks complete in
the spec and update HANDOFF.md to record the second-installment scope.
Add the AST-aware scanner used during verification under the spec
directory so future audits can re-run it.
Extend scripts/ci/i18n_cjk_guard.py with a third check that fails any
PR introducing a key in only one of locales/en.json / locales/zh.json.
The new check runs alongside the existing CJK-clean and per-path
ratchet checks, with no short-circuit and the same single-exit-code
contract; the workflow file and CLI flags are untouched.
Live catalogues are already parity-clean (962 keys per side), so the
guard ships green. This addresses acceptance criterion 4 of the
English-support epic ("for every externalized log message, matching
log.* keys exist in both locales/en.json and locales/zh.json") with a
permanent automated guard, complementing the CJK-clean ratchet from #26.
Refs #11
Translate the system prompt and the individual / group persona prompt
builders in backend/app/services/oasis_profile_generator.py from
Chinese to English. The base prompt language was biasing persona
prose (bio, persona, profession, interested_topics) toward Chinese
even under Accept-Language: en, despite the existing
get_language_instruction() postfix mechanism. Translating the base
prompts removes that bias.
All locale-steering call sites are preserved verbatim (the inline
{get_language_instruction()} in each builder, the system-prompt
assembly), so non-English locales continue to receive Chinese output
of equivalent quality. Locale-independent constraints stay English
inside the prompt: gender stays the literal "male"/"female" enum
for individuals and "other" for groups; age stays an integer (30
for institutional accounts). The two attrs_str / context_str fallback
defaults ("无", "无额外上下文") are translated to "None" /
"No additional context" so they compose with the English body.
The country-language hint country: 国家（使用中文，如"中国"） is
dropped during translation; locale now decides the country language
via the postfix.
Out of scope (untouched): logger calls (issue #6, already merged),
docstrings and comments (issue #7), the rule-based fallback
_generate_profile_rule_based, and the resilience helpers
_fix_truncated_json / _try_fix_json. No public API change, no new
dependencies, no edits outside the target file.
Closes#3
Adds a stdlib-only Python script and a new GitHub Actions workflow
that fail any pull request which reintroduces CJK characters into
locales/en.json or which raises the total CJK match count under
backend/app or frontend/src above a committed per-path baseline.
The guard captures the two highest-signal checks of the larger
i18n-e2e-english-verification audit so it can run on every PR with a
sub-second budget and without depending on that pipeline being on
main. The committed baseline lets the codebase ratchet down toward
English-only without blocking unrelated PRs on pre-existing CJK
content; refresh it intentionally via the documented flag.
Closes#26
The oasis_profile_generator.py system prompt, both user-message
templates (individual + group personas), the context-builder section
labels embedded into the prompt context, the fallback persona templates,
and the per-batch console output banners were all written in Chinese.
Even when Accept-Language was en, the Chinese base prompt and embedded
section labels biased the LLM toward Chinese persona output.
Translate every owned prompt-assembly literal to English while
preserving all functional contracts: f-string interpolations, the
required JSON output keys, the gender/age literal-token rules, the
get_language_instruction() postfix call sites, the _normalize_gender
mapping (which still accepts Chinese gender keys from upstream),
and the rule-based country: "中国" data default. Logger calls,
docstrings, and inline comments are out of scope (issues #6 / #7)
and were not touched.
Closes#25
Replace the last hard-coded Chinese log/print strings in the Flask
graph API, OASIS profile generator, and retry utility with calls to
the existing t() helper, completing the backend i18n coverage started
by ticket #6 so EN-locale operators see English logs end to end.
Adds nine entries to locales/{en,zh}.json: log.graph_api.m027-m029,
log.profile_generator.m024-m025, and a new log.retry.m001-m004
sub-namespace for the retry utility.
Closes#24
Routes ~50 hard-coded Chinese literals across Process.vue, Step2EnvSetup.vue,
Step3Simulation.vue, Step4Report.vue and Step5Interaction.vue through
vue-i18n, with corresponding entries added in lockstep to locales/en.json and
locales/zh.json (1031 -> 1101 lines each, parity preserved). En-locale users
no longer see Chinese in headers, status messages, error fallbacks, project-
info modals, or chat-history prompt construction.
Backend-coupled regex parsers in Step4Report.vue (28 markers + no-reply
predicate + log-severity helper) are centralised into a frozen REPORT_MARKERS
block at the top of <script setup>, with each entry comment-anchored to its
canonical source line in backend/app/services/zep_tools.py. The block is
allowlisted in the audit script so future English alternates can be added
inline once the backend prompts are translated under spec
i18n-report-agent-prompts (issue #25). The Step2EnvSetup stage watcher gets
the same treatment: a STAGE_PHASE_MAP collapses three Chinese-string
equality checks into a lookup that already accepts both legacy Chinese
display strings and the snake_case backend identifiers.
Adds frontend/scripts/audit-i18n-strings.sh as a local verifier (the
referenced .kiro/specs/i18n-e2e-english-verification audit script no longer
exists). The script greps the five files for non-allowlisted CJK literals,
diffs en.json/zh.json key sets, and guards against an en.json CJK regression
(per #20 / spec i18n-backfill-zh-json). Exits 0 on success.
Closes#23
Replace the silent placeholder-UUID fallback in
_GraphNamespace.add_batch with logger.exception(...) + raise so
embedder misconfiguration (404 unknown model, connection refused, etc.)
fails the surrounding graph-build Task with a visible error instead of
producing a Task that looks completed while the graph stays empty.
Document the existing-but-undocumented Ollama embedder configuration
in .env.example, CLAUDE.md, README.md, and docker-compose.yml.
mxbai-embed-large is the recommended local model because its 1024-dim
output matches Graphiti's default EMBEDDING_DIM. Adds a curl smoke
test to verify embedder reachability before the first graph build.
No new env var or provider literal: Ollama is reached through the
existing openai-provider branch by setting EMBEDDING_BASE_URL,
EMBEDDING_API_KEY, and EMBEDDING_MODEL.
Closes#18
Replace the chinese tagline on README.md and README-EN.md with the
existing english subtitle (collapsing the duplicate stack), and switch
the package.json and backend/pyproject.toml description fields to
english so the project's metadata surface no longer surprises
non-chinese readers.
Rename nine chinese-named static image files under static/image/ to
ASCII slugs (six screenshots, two video covers, the QQ-group image)
via git mv so rename history is preserved, and update every <img src>
in README.md, README-EN.md, and README-ZH.md to the new paths. The
chinese body text of README-ZH.md is preserved by design.
A ripgrep scan for chinese characters in README.md and README-EN.md
(excluding the language-switcher line) now returns zero matches,
satisfying the ticket's acceptance criteria.
Closes#12
Spec under .kiro/specs/i18n-e2e-english-verification/ defines a read-only
verification pipeline that classifies every CJK match in backend/app,
frontend/src, and locales/en.json into deliberate / gap / non-applicable /
review-needed, plus a four-class follow-up grouping (frontend ui strings,
backend log strings, backend prompt-label strings, permanent ci guard).
The captured baseline run at audit/9dcaecd2.../ shows 2916 matches: 237
gaps actionable in follow-up issues #23#24#25#26 (filed by this run),
2299 deliberate (covered by issue #7), and 380 review-needed soft signals.
The verification report comment is posted on issue #10. Locale catalogues
are at full key parity (953/953) and locales/en.json is CJK-clean.
The spec is verification-only: production source under backend/app,
frontend/src, and locales is intentionally untouched. Live UI and
docker-compose walkthrough items in the issue checklist are reported as
manual-pending, with reproduction steps and a re-runnable audit script.
Closes#10
Translate chinese developer comments in frontend/src/ to english so
non-chinese-reading maintainers can understand intent without translation
tooling. Pure documentation cleanup with no runtime behavior changes.
Twenty files updated across views, components, api services, App.vue, and
pendingUpload.js. Region-eligibility matrix from .kiro/specs/i18n-
frontend-comments/design.md drives every edit:
- Translate `//`, `/* */`, JSDoc, and Vue `<!-- -->` template comments.
- Drop comments that merely restate the code per dev-guidelines.md.
- Translate console.error/warn/log argument strings (developer-facing).
- Append (#9) to the single chinese-content TODO in views/Process.vue.
Five files retain documented chinese string literals per requirements 1.5
and 4.4: hardcoded UI text and error fallbacks (Process.vue, Step3Simulation.vue),
backend-format regex patterns and i18n-keyed UI labels (Step4Report.vue),
backend stage-key matchers (Step2EnvSetup.vue), and LLM prompt templates
sent to a chinese-tuned model (Step5Interaction.vue). Translating any of
these would either be out of scope (UI strings belong in /locales/*.json)
or would change runtime behavior.
Verification: `rg '[\x{4e00}-\x{9fff}]' frontend/src/` returns 5 documented
files; `npm run build` exits 0 with the same Vite output as before.
Closes#9
translate nine user-facing english values (step3/step4/step5 waiting
states, step5 interactive tools and report-agent chat panel, graph
panel labels) plus the user-visible step 2 log line `log.prepareTaskId`
to natural chinese, so chinese-locale users no longer see english text
mixed into the chinese ui.
`home.heroDescBrand` is intentionally left as the literal `MiroFish`
because it is a brand name. `log.prepareTaskId` was translated rather
than kept english because it is rendered into the in-ui log panel via
`Step2EnvSetup.vue:801` and every surrounding `log.*` value in zh.json
is already translated; the leading two-space indent, the `└─`
continuation glyph, and the `{taskId}` placeholder are preserved.
en.json and zh.json key sets remain identical
(`paths(scalars)` diff is empty); no frontend code is changed.
Closes#8
Extract every Chinese string inside backend logger.{info,warning,error,
debug,exception} calls and inside user-facing jsonify({"error|message":
...}) responses across the listed in-scope modules into
locales/{en,zh}.json under nested namespaces (log.<module>.*,
api.{error,message}.<scope>.*). Locale dictionaries stay structurally
identical; the existing flat frontend-facing keys at log.* / api.* are
left untouched. The locale helper (backend/app/utils/locale.py) now
emits a single deduplicated mirofish.locale warning per (locale, key)
pair when a translation is missing instead of silently returning the
raw key, so unknown keys are visible without crashing requests or
background tasks. A repo-root scripts/check_i18n_logs.py verifier
performs an AST-aware source scan for residual Chinese inside the
in-scope logger/jsonify calls and a recursive parity diff between
en.json and zh.json — both modes pass.
Why: backend logs and API errors previously emitted Chinese-only
strings, leaving English-speaking operators with unreadable log
aggregator output and API consumers with locale-mismatched error
messages. The t() helper and per-thread set_locale propagation already
existed; this change makes every backend caller route through them.
Closes#6
translate every llm-facing string-literal in
backend/app/services/report_agent.py — the four tool-description
constants, the plan/section/chat system+user prompts, the react loop
templates, the inline messages re-injected during the section and chat
loops, the _execute_tool error returns, and the plan_outline default and
fallback outline content. preserve every {interpolation} token, the
literal final answer: trigger and <tool_call> xml tag, the four primary
tool names, and all three get_language_instruction() postfix call sites.
also switch the unused-tools join separator from "、" to ", " so it
renders naturally inside the now-english react templates.
removes the chinese language bias that the english postfix alone could
not overcome — under accept-language: en the report agent now produces
english-flavoured analytical reports and chat replies; under
accept-language: zh the postfix continues to steer the model into
chinese with no semantic delta. logger calls (#6) and docstrings or
comments (#7) are deliberately untouched.
Closes#5
translate the three llm prompt blocks plus the two prompt-feeding helpers
(_build_context, _summarize_entities) in
backend/app/services/simulation_config_generator.py from chinese to english.
the chinese base prompts were biasing the model toward chinese structure
and lexical choice for content, narrative_direction, hot_topics, and
reasoning fields even when accept-language was en, because
get_language_instruction() only steers the response language as a
postfix.
translation is in-place and preserves every functional contract: the
json output schema for all three prompts, every variable interpolation,
the per-entity-type heuristic ranges in the agent-config prompt, the
trailing english IMPORTANT directives that lock poster_type to
PascalCase and stance to {supportive,opposing,neutral,observer}, and
all three get_language_instruction() postfix call sites. the two
default-path reasoning literals are translated to locale-agnostic
english so generation_reasoning no longer mixes chinese and english on
the failure path.
logger calls, docstrings, and inline comments are intentionally left
chinese (out of scope; covered by issues #6 and #7). public api,
dataclasses, class constants, and the SimulationParameters payload
shape are unchanged.
Closes#4
translate the system prompt constant and the user-message template in
backend/app/services/ontology_generator.py from chinese to english.
the chinese base prompt was biasing the model toward chinese structure
and word choice even when accept-language was en, leaving ontology
descriptions and analysis_summary fields chinese-flavoured.
translation is in-place and preserves every functional contract: the
json output schema, the entity-type and relationship-type taxonomies
verbatim, the reserved-attribute-name list, the count and length
constraints, and all f-string interpolations. the
get_language_instruction() postfix call site and the trailing english
identifier-format directive are unchanged, so zh and other locales
continue to receive locale-appropriate descriptions.
logger calls, docstrings, and inline comments are intentionally left
in chinese — they are owned by issues #6 and #7.
a small static guard script (backend/scripts/test_ontology_prompts_no_cjk.py)
ast-parses the module and asserts zero cjk in the system prompt and in
every string literal of _build_user_message except the docstring, so
the regression cannot reappear silently.
Closes#2
Adds a Neo4j service to docker-compose so `docker compose up -d` works
on a clean checkout, and unhardcodes Graphiti's LLM/embedder so the
documented default provider (Qwen via Dashscope) actually works.
- docker-compose: neo4j:5-community service with cypher-shell
healthcheck, named volumes, and `depends_on: service_healthy` on the
app container; in-Docker NEO4J_URI override leaves the host-mode
default untouched.
- Config: new GRAPHITI_LLM_PROVIDER (openai|gemini, default openai) plus
optional EMBEDDING_API_KEY / EMBEDDING_BASE_URL that fall back to the
chat LLM credentials.
- graphiti_adapter: provider switch inside the singleton factory with
lazy per-provider imports; Gemini path is preserved exactly. The
no-op `_GeminiReranker` becomes a provider-agnostic
`_PassthroughReranker`, still injected explicitly so Graphiti does
not fall back to its OpenAI-only default reranker.
- Drop the ignored `reranker=` kwarg from `_GraphNamespace.search` and
the misleading callers in `zep_tools.py` and
`oasis_profile_generator.py`.
- Refresh `.env.example` to mirror the README env section.
Spec, requirements, and design under
`.kiro/specs/graphiti-neo4j-finalize/`.
Closes#1
Add .kiro/steering/ as persistent project memory for CC-SDD / Kiro
workflows. Three core files (product, tech, structure) capture
purpose, stack, and organization patterns; three custom files
(database, api-standards, error-handling) pin the load-bearing
project-specific conventions:
- group_id isolation and the Graphiti adapter / event-loop singleton
- {success, data|error} envelope and the Task polling contract
- reasoning-model output stripping and the retry_with_backoff helper
Files focus on patterns and decisions, not catalogs, per the
steering-principles "golden rule".
Adopt CC-SDD (Kiro) as the project's spec-driven planning tool, with
plans persisted in .kiro/specs/ and a checkpoint after every task
(strictest cadence — no code without an approved plan).
CC-SDD install (via npx cc-sdd@latest --claude --lang en):
- .kiro/settings/rules/: EARS format, gap-analysis, design and
requirements review gates, design discovery, tasks generation,
steering principles, parallel-task analysis.
- .kiro/settings/templates/: specs (init, requirements, design, tasks,
research) and steering (product/tech/structure plus optional
api-standards/auth/db/deployment/error-handling/security/testing).
- .claude/commands/kiro/: 11 Kiro slash commands — spec-init,
spec-requirements, spec-design, spec-tasks, spec-impl, spec-status,
steering, steering-custom, validate-gap, validate-design,
validate-impl.
Local additions:
- .claude/commands/plan.md: /plan [task] wrapper that picks up the task
from $ARGUMENTS or a single .ticket/<n>.md snapshot, walks the Kiro
flow (steering -> spec-init -> spec-requirements -> validate-gap ->
spec-design -> validate-design -> spec-tasks) and stops for human
approval after each artefact. Refuses "just code it" requests.
- .claude/hooks/session_start.sh: extend to print active tickets
(.ticket/*.md) and open specs (.kiro/specs/*/) with phase from
spec.json, alongside the existing branch/state line.
Documentation: .claude/onboarding/step4_workflow/01_tool_decision.md
Adapt the Notion onboarding prompt — originally Jira/MCP-oriented — to
this project's actual issue tracker (GitHub at
salestech-group/MiroFish) using the gh CLI.
Slash commands (.claude/commands/):
- /ticket <number>: fetch a GitHub issue via gh, self-assign, try to
add an in-progress label (skips silently if the label doesn't exist),
and snapshot the issue (frontmatter + body) to .ticket/<n>.md so
later planning steps can read the description without refetching.
- /ticket-list: interactive overview of issues; asks for filters
(open/closed, status, assignee, milestone, labels) and runs a single
gh issue list with the answers, rendering a compact markdown table.
Workspace:
- .ticket/repo.md declares the target repo (GitHub equivalent of the
Jira "board.md" referenced in the prompt).
- .gitignore: ignore .ticket/* except repo.md and .gitkeep so cached
ticket markdowns stay local.
Settings:
- Allow-list gh issue view/list/edit/comment, gh repo view,
gh pr view/list, gh auth status to avoid permission prompts.
Documentation: .claude/onboarding/step3_planning/01_ticket_sync.md
Dominik Seemann
Dominik Seemann