feat: add RAG and Vector DB scaffolding support (--rag, --template, --vector-db) by robertchoi · Pull Request #103 · Proact0/act-operator

robertchoi · 2026-10-07T12:09:41Z

🚀 PR Type (Required)

Select one and delete the others:

[ V] 🎯 Ready for Review - All quality checks passed, ready for merge
🔄 Draft/WIP - Early feedback welcome (tests/docs may be incomplete)
⚡ Quick Fix - Urgent fix requiring expedited review

Proact0 Culture: We value early collaboration! Draft PRs are encouraged for complex changes.

📝 Summary

Adds --rag, --template (default | rag), and --vector-db (chroma | pgvector | inmemory) options to both act new and act cast CLI commands.
Implements conditional scaffolding for RAG pipeline components:
- Models: Added embedding (get_embedding_model) and chat model factory functions.
- Tools: Added retrieve_documents tool with Vector DB hooks.
- State: Extended state schemas with context and retrieved_docs.
- Nodes: Integrated document retrieval in workflow nodes for RAG templates.
- Dependencies: Added conditional dependencies for chromadb and pgvector.
Added automated integration tests covering all new flags in test_cli.py.

📄 Description

🔗 Issue / Dependencies / Mentions

Issue: Fixes feat: add RAG and Vector DB scaffolding template option to act cast (--rag) #102
Dependencies:
SNS handle:

💪 Ownership (Required)

[V ] Hand-raise: I will monitor the impact of this change and take responsibility for follow-up issues

Extreme Ownership: At Proact0, we track not just code changes, but their impact on team productivity.

✅ Quality Checks (Required for "Ready for Review" only)

[V] uv run ruff check . passed
[V] uv run pytest -q passed

Draft/WIP PRs: Skip quality checks for early feedback - just mark as Draft!

💡 Notes (Optional)

🔗 Related Issue(s)

…to exclude study-related directories.

…ect naming convention.

…ation files

…ugh 4

…-vector-db) - Add --rag, --template (default|rag), and --vector-db (chroma|pgvector|inmemory) options to act new and act cast CLI commands. - Implement conditional cookiecutter scaffolding for RAG pipeline components: - modules/models.py: Added embedding and chat model provider factory functions. - modules/tools.py: Added retrieve_documents tool with Vector DB integration hooks. - modules/state.py: Added context and retrieved document fields to state schemas. - modules/nodes.py: Wired document retrieval into sample workflow nodes. - pyproject.toml: Added dependencies for langchain-community, chromadb, and pgvector. - Add comprehensive integration tests in test_cli.py verifying --rag, --template, and --vector-db options.

Copilot

Copilot review overview

🟡 Changes recommended

Backend selection is currently nonfunctional, dependencies remain commented out, and generated RAG projects fail a bundled test.

Review effort: Balanced
Findings: 3 · 5 · 11

Open (19)

Generated RAG project fails the bundled default test · New
Backend dependencies are omitted from generated projects · New
User-controlled tenant ID enables cross-user memory access · New
Template option accepts unsupported values · New
Vector database options accept unsupported values · New
Selected vector database backend is ignored · New
Unsupported contact_info detector provides no masking · New
Missing message reducer drops user conversation history · New
Examples use the wrong path option · New
Absolute local file URL breaks repository links · New
Curriculum URL is machine-local · New
Local Windows path breaks the guide link · New
Curriculum link uses a local Windows path · New
Week-All link uses an absolute local URL · New
Workstation-specific curriculum link is broken · New
Absolute Windows curriculum URL is broken · New
Integrated guide uses the wrong graph entrypoint path · New
Graph entrypoint is documented at the wrong path · New
Slide command uses the wrong path option · New

What changed in this PR

Extends Act Operator’s CLI and templates with RAG scaffolding options, alongside substantial curriculum documentation.

Changes:

Adds --rag, --template, and --vector-db CLI options.
Adds RAG state, retrieval, model, dependency, and test templates.
Adds developer guidance and an eight-week learning curriculum.

File	Description
`.agent/workflows/notebooklm-slide.md`	Adds slide-generation workflow guidance.
`.gitignore`	Ignores study-generated projects.
`AGENTS.md`	Adds repository and contributor guidance.
`act_operator/act_operator/cast_scaffolder.py`	Passes RAG settings when adding Casts.
`act_operator/act_operator/cli.py`	Wires new options into CLI commands.
`act_operator/act_operator/cli_options.py`	Declares RAG and backend options.
`act_operator/act_operator/project_scaffolder.py`	Adds RAG template context.
`act_operator/act_operator/scaffold/cookiecutter.json`	Adds RAG template defaults.
`scaffold/.../README.md`	Documents generated RAG Casts.
`scaffold/.../pyproject.toml`	Adds conditional backend dependency templates.
`scaffold/.../modules/models.py`	Adds model factories.
`scaffold/.../modules/nodes.py`	Adds retrieval-enabled sample node.
`scaffold/.../modules/state.py`	Adds RAG state fields.
`scaffold/.../modules/tools.py`	Adds sample retrieval tool.
`scaffold/.../tests/cast_tests/..._test.py`	Adds RAG output assertions.
`act_operator/act_operator/tests/integration/test_cli.py`	Tests new CLI flags.
`study/README.md`	Adds curriculum index.
`study/Week1.md`	Adds setup and architecture guide.
`study/Week1ppt.md`	Adds Week 1 slides.
`study/Week2.md`	Adds implementation guide.
`study/Week2ppt.md`	Adds Week 2 slides.
`study/Week3.md`	Adds middleware guide.
`study/Week3ppt.md`	Adds Week 3 slides.
`study/Week4.md`	Adds engineering guide.
`study/Week4ppt.md`	Adds Week 4 slides.
`study/Week-All.md`	Adds consolidated guide.
`study/W21.md`	Adds research-agent project guide.
`study/W22.md`	Adds HITL email guide.
`study/W23.md`	Adds supervisor-pattern guide.
`study/W24.md`	Adds persistent RAG guide.
`study/W25.md`	Adds episodic-memory guide.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

+            "result": welcome,
+            "context": context,
+            "retrieved_docs": [context],
+            "messages": [AIMessage(content=f"{welcome} (Context: {context})")],


+    # "langchain-postgres>=0.0.12",
+    # "psycopg[binary]>=3.1.0",
+{% elif cookiecutter.vector_db == 'chroma' %}
+    # "langchain-chroma>=0.2.0",
+    # "chromadb>=0.5.0",
+{% endif %}
+    # "langchain-openai>=0.3.0",


+class MemoryState(TypedDict):
+    user_id: str
+    messages: list[BaseMessage]
+    recalled_memories: list[str]


+TEMPLATE_OPTION = typer.Option(
+    "default",
+    "--template",
+    "-t",
+    help="Template type to scaffold (default|rag)",
+)


+VECTOR_DB_OPTION = typer.Option(
+    "chroma",
+    "--vector-db",
+    help="Vector DB engine for RAG template (chroma|pgvector|inmemory)",
+)


+# 지속성 메모리 기반 RAG 챗봇 (Persistent RAG Knowledge Base)
+
+> **문서 정의**: 사내 문서 및 지식 베이스를 검색하는 **RAG(검색 증강 생성)** 기능에, 세션이 끊겨도 사라지지 않는 **장기 기억(Long-term Memory) 및 상태 영속성(Persistence)** 메커니즘을 결합한 지능형 에이전트 시스템 가이드입니다.  
+> **관련 커리큘럼**: [Act Operator 7주차 프로젝트](file:///d:/git/act-operator/study/README.md#L131-L139) · LangGraph 1.0+ · `uv` workspace 기준


+# 장기 기억 기반 사용자 맞춤형 업무 비서 (Long-term Episodic Memory)
+
+> **문서 정의**: 일회성 세션(단기 대화)을 넘어 사용자의 과거 지시 사항, 교정 피드백, 업무 스타일, 프로젝트 맥락을 **임베딩 및 벡터 데이터베이스**에 구조화된 지식으로 축적하고, 새로운 요청 시 의미적 유사도(Semantic Similarity)로 관련 기억을 자동 회상(Recall)하여 1:1 맞춤형 결과물을 산출하는 에피소딕 메모리 에이전트 가이드입니다.  
+> **관련 커리큘럼**: [Act Operator 심화 프로젝트](file:///d:/git/act-operator/study/README.md) · LangGraph 1.0+ · `langgraph.store` & Vector DB · `uv` workspace 기준


+│       ├── modules/                ← 핵심 컴포넌트 디렉터리
+│       │   ├── state.py            ← [필수] State/InputState/OutputState 스키마
+│       │   ├── nodes.py            ← [필수] BaseNode 상속 노드 구현체
+│       │   ├── graph.py            ← [필수] StateGraph 조립 및 컴파일 진입점


+│       ├── modules/                ← 핵심 컴포넌트 디렉터리
+│       │   ├── state.py            ← [필수] State/InputState/OutputState 스키마
+│       │   ├── nodes.py            ← [필수] BaseNode 상속 노드 구현체
+│       │   ├── graph.py            ← [필수] StateGraph 조립 및 컴파일 진입점
+│       │   ├── agents.py           ← [선택] create_agent 기반 에이전트
+│       │   ├── tools.py            ← [선택] @tool 도구 정의
+│       │   ├── models.py           ← [선택] LLM 모델 설정
+│       │   ├── conditions.py       ← [선택] 조건부 라우팅 함수
+│       │   ├── middlewares.py      ← [선택] 라이프사이클 미들웨어
+│       │   ├── prompts.py          ← [선택] 프롬프트 템플릿
+│       │   └── utils.py            ← [선택] 헬퍼 유틸리티
+│       ├── README.md               ← Cast 전용 설명서


+
+**슬라이드 내용**
+- **신규 Cast 스캐폴딩과 그래프 등록**
+- CLI 명령어: `uv run act cast --act-path . --cast-name "Data Preprocessor" --lang kr`


robertchoi added 20 commits January 7, 2026 13:27

[ADD] .antigravity workflow folder

759bce2

Merge branch 'main' of https://github.com/WithModulabs/act-operator

e9db6b0

Merge branch 'Proact0:main' into main

fcbfb63

Merge branch 'Proact0:main' into main

d7d09d5

Merge branch 'Proact0:main' into main

8204e85

chore: remove a file

5fe6aa7

feat: Add README for study directory.

aed9e62

Merge branch 'Proact0:main' into main

c0ee610

feat: Add initial study materials for weeks 1-4 and update gitignore …

8c139e0

…to exclude study-related directories.

docs: Add Week2 study notes and update gitignore entry for study proj…

d709ee3

…ect naming convention.

Merge branch 'Proact0:main' into main

b32be5f

Merge branch 'Proact0:main' into main

0229cc2

Merge branch 'Proact0:main' into main

815260a

feat: add Week 3 presentation study notes

a143c5f

docs: add AGENTS.md reference guide and 8-week curriculum documentation

aea7e11

feat: add my-act directory to gitignore and initialize study document…

84ce0cc

…ation files

docs: add study materials and progress documentation for weeks 1 thro…

fc3d4e4

…ugh 4

docs: add study notes and architecture diagrams for W23 and W24

53cb89b

docs: add weekly study notes for W21, W22, and W25

efcbf1a

Copilot AI balanced review requested due to automatic review settings October 7, 2026 12:09

Copilot started reviewing on behalf of robertchoi October 7, 2026 12:10

View session

Copilot AI reviewed Oct 7, 2026

View reviewed changes

Navigation Menu

Repository navigation

feat: add RAG and Vector DB scaffolding support (--rag, --template, --vector-db) - #103

feat: add RAG and Vector DB scaffolding support (--rag, --template, --vector-db)#103
robertchoi wants to merge 20 commits into
Proact0:mainfrom
WithModulabs:feat/rag-scaffolding-template

robertchoi commented Oct 7, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

robertchoi commented Oct 7, 2026

🚀 PR Type (Required)

📝 Summary

📄 Description

🔗 Issue / Dependencies / Mentions

💪 Ownership (Required)

✅ Quality Checks (Required for "Ready for Review" only)

💡 Notes (Optional)

🔗 Related Issue(s)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants