Skip to content

[ai-assisted] feat(ai): support vector projection umap tsne#391

Merged
donghyuck merged 2 commits into2.xfrom
codex/issue-390-vector-projection-algorithms
Apr 30, 2026
Merged

[ai-assisted] feat(ai): support vector projection umap tsne#391
donghyuck merged 2 commits into2.xfrom
codex/issue-390-vector-projection-algorithms

Conversation

@donghyuck
Copy link
Copy Markdown
Owner

Why

  • Vector Map 화면에서 PCA 외 UMAP, TSNE Projection을 선택할 수 있어야 합니다.
  • 클라이언트는 embedding 원본이나 차원 축소 계산을 수행하지 않고, 서버가 미리 생성해 저장한 x, y 좌표만 렌더링해야 합니다.

What

  • ProjectionAlgorithmUMAP, TSNE를 추가했습니다.
  • UmapVectorProjectionGenerator, TsneVectorProjectionGenerator를 추가했습니다.
    • PCA 초기 좌표를 사용합니다.
    • embedding cosine distance 기반 이웃 보존 attraction/repulsion refinement를 deterministic하게 수행합니다.
    • 외부 대형 수치 라이브러리는 추가하지 않았습니다.
  • PCA 계산 공통부를 ProjectionCoordinateSupport로 분리했습니다.
  • starter auto-configuration에서 PCA/UMAP/TSNE 기본 generator를 등록합니다.
  • 동일 알고리즘의 사용자 구현이 있으면 기본 구현보다 우선 사용하도록 DefaultVectorProjectionJobService를 보강했습니다.
  • Projection 생성 요청에서 algorithm: "UMAP", algorithm: "TSNE"를 처리하고, 미지원 알고리즘은 기존처럼 400으로 거부합니다.
  • README에 서버 측 알고리즘 처리 방식과 클라이언트 좌표 사용 계약을 문서화했습니다.

Related Issues

Validation

  • Command: ./gradlew :studio-platform-ai:test :starter:studio-platform-starter-ai:test :starter:studio-platform-starter-ai-web:test
  • Result: PASS
  • Command: ./gradlew test
  • Result: PASS
  • Command: git diff --check
  • Result: PASS

Risk / Rollback

  • Risk: UMAP/t-SNE는 dependency-free deterministic 구현이므로 전문 수치 라이브러리 기반 구현보다 시각화 품질이 제한될 수 있습니다. API와 저장 구조는 기존 projection 계약을 유지합니다.
  • Rollback: 이 PR의 커밋을 revert하면 PCA-only 동작으로 복구됩니다.

AI / Subagent Usage

  • AI-assisted: Yes
  • Subagent used: Yes
  • Delegated scope: Vector Projection UMAP/t-SNE 알고리즘 지원 #390 변경안 코드 리뷰 및 generator precedence 보완 후 재리뷰
  • Main author validation: 리뷰 지적을 반영해 사용자 generator 우선순위와 auto-configuration 테스트를 보강하고 전체 테스트를 실행했습니다.

Checklist

  • commit message follows policy
  • issue template used or exception recorded
  • AI-Assisted value is correct
  • validation recorded
  • subagent usage recorded when used
  • CI / repository verification passed
  • human review completed before merge
  • no unrelated changes included

Issue:
- Closes #390

Why:
- Vector Map needs server-side UMAP and t-SNE projection choices in addition to PCA.
- The client should keep rendering stored x/y coordinates without embedding or projection calculation.

What:
- Add UMAP and TSNE ProjectionAlgorithm values.
- Add dependency-free server-side UMAP/t-SNE-style projection generators using PCA initialization and embedding-neighbor refinement.
- Register PCA/UMAP/TSNE default generator beans and preserve SPI replacement by preferring non-default same-algorithm generators.
- Update vector projection docs and tests for algorithm parsing, generator output, service selection, and auto-configuration registration.

Validation:
- ./gradlew :studio-platform-ai:test :starter:studio-platform-starter-ai:test :starter:studio-platform-starter-ai-web:test (PASS)
- ./gradlew test (PASS)
- git diff --check (PASS)

AI-Assisted: Yes
Subagent used: Yes
Delegated scope: code review for issue #390 before and after generator precedence fix
Issue:
- #390

Why:
- Review found that multiple default VectorProjectionGenerator beans could break single-type injection and that fixed-stride repulsion sampling collapsed for projection sizes divisible by 37.

What:
- Mark the default PCA projection generator as primary to preserve single VectorProjectionGenerator injection compatibility.
- Add auto-configuration coverage for interface bean resolution and custom generator inclusion in the job service.
- Use a projection-size coprime stride for repulsion sampling and add regression coverage for 37/74 item sizes.

Validation:
- ./gradlew :studio-platform-ai:test :starter:studio-platform-starter-ai:test :starter:studio-platform-starter-ai-web:test (PASS)
- ./gradlew test (PASS)
- git diff --check (PASS)

AI-Assisted: Yes
Subagent used: Yes
Delegated scope: PR #391 blocker review and re-review
@donghyuck
Copy link
Copy Markdown
Owner Author

리뷰 결과를 반영해 보완 커밋을 추가했습니다.

처리한 리뷰 지적:

  • VectorProjectionGenerator 단일 타입 주입 호환성 보존
    • 기본 PCA generator에 @Primary 적용
    • context.getBean(VectorProjectionGenerator.class)가 PCA로 해소되는 auto-configuration 회귀 테스트 추가
    • 사용자 정의 same-algorithm generator가 job service에 포함되는 Spring context 테스트 추가
  • repulsion sampler의 fixed stride collapse 수정
    • projection size와 서로소인 stride를 선택하도록 변경
    • 37/74 item size에서 sample peer 중복이 생기지 않는 회귀 테스트 추가

검증:

  • ./gradlew :studio-platform-ai:test :starter:studio-platform-starter-ai:test :starter:studio-platform-starter-ai-web:test PASS
  • ./gradlew test PASS
  • git diff --check PASS

재리뷰 결과: blocking finding 없음.

@donghyuck donghyuck merged commit 8ceeb8a into 2.x Apr 30, 2026
2 checks passed
@donghyuck donghyuck deleted the codex/issue-390-vector-projection-algorithms branch April 30, 2026 11:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant