Skip to content

Commit 386eaef

Browse files
codekilncodekiln
committed
docs: Add comprehensive report on OpenDeepResearch GitHub Action for LogSeq integration
- Introduce a new report detailing the design and implementation of a GitHub Action that automates Deep Research using LangChain's OpenDeepResearch. - Include a survey of existing tools, integration approaches, and a prototype workflow for processing Markdown files in LogSeq. - Update journal entries to reflect new insights and considerations for API management, security, and cost optimization.
1 parent 78c6877 commit 386eaef

File tree

3 files changed

+247
-2
lines changed

3 files changed

+247
-2
lines changed

‎journals/2025_11_01.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@
77
user: list files command? assistant: ls
88
- ## On [[iOS/App/Development]] and Walled Gardens
99
- Thinking about [[Person/Maggie Appleton/Talk/24/05/Home-Cooked Software and Barefoot Developers]]; considering making a few different home apps.
10-
-
1110
- Learned about distributing iOS apps to family devices - three main options:
1211
- Free sideloading (impractical - expires after 7 days)
1312
- TestFlight via Apple Developer Program ($99/year) - recommended, easy for family, but builds expire after 90 days

‎journals/2025_11_08.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,4 +17,6 @@
1717
- #Examples at https://books.37signals.com/
1818
- [The Prophet](https://classics.37signals.com/8/the-prophet)
1919
- [In our Time](https://classics.37signals.com/7/in-our-time)
20-
- [The United States Constitution](https://books.37signals.com/10/the-united-states-constitution).
20+
- [The United States Constitution](https://books.37signals.com/10/the-united-states-constitution).
21+
- ## #[[AI Deep Research]]
22+
- [[Logseq/AI/Deep Research/Report/Github Action Idea]] - Created comprehensive research report surveying tools and precedents for building a GitHub Action that automates Deep Research using LangChain's OpenDeepResearch (LangGraph) for LogSeq Markdown pages tagged with `deep-research-prompt`. The report covers existing GitHub Actions patterns, integration approaches (containerized vs API-based), API aggregator options, security considerations, and provides a prototype workflow with recommendations for MVP and production implementations.

‎pages/Logseq___AI___Deep Research___Report___Github Action Idea.md‎

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
tags:: [[AI Deep Research]], [[Report]]
2+
3+
- # OpenDeepResearch GitHub Action for LogSeq Integration: Survey and Implementation Analysis
4+
- ## Overview
5+
- This report surveys tools, precedents, and implementation approaches for building a GitHub Action that automates Deep Research using LangChain's **OpenDeepResearch (LangGraph)** whenever a LogSeq Markdown page tagged with `deep-research-prompt: "prompt here"` is added to `pages/*.md` in a git repository. The workflow should commit synthesized research results back into the same page. The analysis covers existing GitHub Actions for AI-assisted research workflows, integration patterns for LangGraph-based tools, API aggregator options, and provides a prototype implementation with security and cost considerations.
6+
- ## 1. Survey of Existing Tools and Precedents
7+
- ### 1.1. GitHub Actions for AI-Assisted Research Workflows
8+
- #### 1.1.1. LangChain's GitHub Toolkit
9+
- LangChain provides a GitHub Toolkit that enables Large Language Models (LLMs) to interact with GitHub repositories, facilitating tasks such as reading from and writing to repositories[^1]. This toolkit demonstrates the feasibility of programmatic GitHub repository manipulation within automated workflows and could serve as a foundation for detecting and modifying Markdown files.
10+
- #### 1.1.2. GPT Researcher Integration with LangChain
11+
- LangChain has integrated with GPT Researcher, an open-source research assistant that automates web research tasks[^2]. This integration showcases how research automation can be embedded within LangChain-based workflows, providing a precedent for combining research capabilities with repository automation.
12+
- #### 1.1.3. AI Code Review Agent
13+
- An AI-powered code review agent built with LangChain and GitHub Actions demonstrates the pattern of using GitHub Actions to trigger AI-driven processes and commit results back to repositories[^3]. This serves as a practical example of the event-driven automation needed for the Deep Research workflow.
14+
- #### 1.1.4. GitHub Webhook Integration Patterns
15+
- LangChain's Open SWE integrates with GitHub through webhooks, allowing automated code changes triggered by specific labels on issues[^4]. This pattern can be adapted to monitor for new Markdown files with specific front-matter tags, providing an alternative to push-based detection.
16+
- ### 1.2. Markdown-Based PKM Automation Precedents
17+
- While specific examples of GitHub Actions for Obsidian or LogSeq automation are less common in public repositories, the general pattern of monitoring Markdown files in version-controlled knowledge bases is well-established. The approach of parsing front-matter, detecting triggers, and committing results back follows standard CI/CD patterns for documentation automation.
18+
- ## 2. OpenDeepResearch Integration Approaches
19+
- ### 2.1. LangChain's OpenDeepResearch Repository
20+
- The OpenDeepResearch project is available at [langchain-ai/open_deep_research](https://github.com/langchain-ai/open_deep_research)[^5]. It uses LangGraph to orchestrate research workflows with multiple search tools including Tavily API, Perplexity API, Exa API, ArXiv, PubMed, Linkup API, DuckDuckGo API, and Google Search API. The system uses a planner LLM for report planning and a writer LLM for report writing, with support for any model integrated with LangChain's `init_chat_model()` API.
21+
- ### 2.2. Containerization Approach
22+
- OpenDeepResearch can be containerized using Docker, enabling it to run within a GitHub Action. This approach ensures a consistent environment and simplifies dependency management. The container would include Python dependencies, LangChain, LangGraph, and the OpenDeepResearch codebase. This method provides full control over the execution environment and allows for local execution without external API dependencies beyond the search tools and LLM providers.
23+
- ### 2.3. API-Based Invocation
24+
- If OpenDeepResearch is deployed as a web service (either self-hosted or via a hosted LangGraph endpoint), the GitHub Action can invoke it via HTTP API calls. This method reduces the complexity of the GitHub Action itself but requires maintaining a separate service. The API approach is more scalable for multiple repositories or high-volume usage but introduces additional infrastructure requirements.
25+
- ### 2.4. Self-Hosted LangGraph Endpoint
26+
- LangGraph can be deployed as a standalone service that exposes research capabilities via API. This approach allows for centralized management of the research infrastructure while enabling multiple GitHub repositories to consume the service. The endpoint would handle LangGraph state management, model initialization, and result streaming.
27+
- ## 3. API Aggregator Options
28+
- ### 3.1. Eden AI
29+
- Eden AI provides a unified API to access various AI services, including OpenAI's endpoints[^6]. While Eden AI aggregates multiple AI providers, it may not directly support OpenAI's Deep Research endpoint (which is a specialized feature). However, Eden AI could be used to access the underlying models (GPT-4, Claude, etc.) that OpenDeepResearch uses for planning and writing, potentially reducing API key management complexity.
30+
- ### 3.2. OpenRouter
31+
- OpenRouter acts as an API aggregator, facilitating access to multiple AI models and services through a single interface[^7]. Similar to Eden AI, OpenRouter provides unified access to various LLM providers but may not directly support Deep Research endpoints. It could serve as a model provider for the planner and writer LLMs within OpenDeepResearch.
32+
- ### 3.3. Direct API Access
33+
- For the MVP, direct API access to OpenAI, Anthropic, or other LLM providers is the most straightforward approach. OpenDeepResearch already supports multiple model providers through LangChain's universal model initialization, so the GitHub Action can configure API keys via GitHub Secrets without requiring an aggregator layer.
34+
- ## 4. Integration Pattern Design
35+
- ### 4.1. Event Detection
36+
- The GitHub Action should trigger on `push` events, specifically monitoring the `pages/` directory for new or modified Markdown files. The workflow can use `paths` filtering to only run when relevant files change:
37+
- ~~~
38+
on:
39+
push:
40+
paths:
41+
- 'pages/*.md'
42+
~~~
43+
- ### 4.2. Front-Matter Parsing
44+
- Markdown files with front-matter can be parsed using libraries such as:
45+
- `yaml-front-matter` (Python)
46+
- `front-matter` (Node.js)
47+
- `front-matter-cli` (command-line tool)
48+
- The script should extract the `deep-research-prompt` field from the front-matter and proceed only if the field exists and contains a non-empty value.
49+
- ### 4.3. Research Invocation
50+
- Upon detecting a valid prompt, the workflow should:
51+
1. Initialize OpenDeepResearch with appropriate model configuration
52+
2. Execute the research workflow with the extracted prompt
53+
3. Wait for completion and retrieve the synthesized report
54+
4. Format the results appropriately for LogSeq Markdown
55+
- ### 4.4. Result Integration
56+
- The research results should be appended to the original Markdown file in a structured format. For LogSeq compatibility, the results should:
57+
- Use proper LogSeq Flavored Markdown (LFM) formatting
58+
- Convert references to LogSeq footnotes (format: `[^1]: url`)
59+
- Maintain hierarchical structure with bullet points
60+
- Include a clear section header (e.g., `## Deep Research Results`)
61+
- ### 4.5. Commit and Push Logic
62+
- After appending results, the workflow should:
63+
- Stage the modified files: `git add pages/*.md`
64+
- Commit with a descriptive message: `git commit -m 'Add deep research results for [page name]'`
65+
- Push changes back to the repository: `git push`
66+
- The workflow must configure Git user identity for the GitHub Actions bot to enable commits.
67+
- ## 5. Prototype GitHub Actions Workflow
68+
- ### 5.1. Complete Workflow YAML
69+
- ~~~
70+
name: Deep Research Automation
71+
72+
on:
73+
push:
74+
paths:
75+
- 'pages/*.md'
76+
77+
jobs:
78+
deep_research:
79+
runs-on: ubuntu-latest
80+
steps:
81+
- name: Checkout Repository
82+
uses: actions/checkout@v4
83+
with:
84+
token: ${{ secrets.GITHUB_TOKEN }}
85+
86+
- name: Set Up Python
87+
uses: actions/setup-python@v5
88+
with:
89+
python-version: '3.11'
90+
91+
- name: Install Dependencies
92+
run: |
93+
pip install langchain langchain-community langgraph open-deep-research pyyaml frontmatter
94+
95+
- name: Process Markdown Files
96+
env:
97+
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
98+
TAVILY_API_KEY: ${{ secrets.TAVILY_API_KEY }}
99+
run: |
100+
python .github/scripts/process_deep_research.py
101+
102+
- name: Commit and Push Changes
103+
run: |
104+
git config --global user.name 'github-actions[bot]'
105+
git config --global user.email 'github-actions[bot]@users.noreply.github.com'
106+
git add pages/
107+
git commit -m 'Automated Deep Research results' || exit 0
108+
git push || exit 0
109+
~~~
110+
- ### 5.2. Processing Script Outline
111+
- The `process_deep_research.py` script should:
112+
1. Scan `pages/*.md` for files modified in the current commit
113+
2. Parse front-matter to detect `deep-research-prompt` tags
114+
3. For each detected prompt:
115+
- Initialize OpenDeepResearch with configured models
116+
- Execute research workflow
117+
- Convert results to LogSeq Markdown format
118+
- Convert references to LogSeq footnotes
119+
- Append results to the file
120+
4. Handle errors gracefully and log processing status
121+
- ## 6. Security and Cost Considerations
122+
- ### 6.1. Rate Limits
123+
- API rate limits must be considered for:
124+
- LLM providers (OpenAI, Anthropic, etc.)
125+
- Search APIs (Tavily, Perplexity, Exa, etc.)
126+
- GitHub API (for commits and repository access)
127+
- The workflow should implement retry logic with exponential backoff and respect rate limit headers.
128+
- ### 6.2. Token Scopes
129+
- GitHub tokens should have minimal necessary permissions:
130+
- `contents: write` for committing changes
131+
- `pull-requests: write` if PR-based workflow is used
132+
- The default `GITHUB_TOKEN` provided to Actions has repository-scoped permissions, which is typically sufficient.
133+
- ### 6.3. API Key Management
134+
- All API keys should be stored in GitHub Secrets:
135+
- `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` for LLM access
136+
- Search API keys (e.g., `TAVILY_API_KEY`, `PERPLEXITY_API_KEY`)
137+
- Secrets should never be logged or exposed in workflow output.
138+
- ### 6.4. Provenance Logging
139+
- The workflow should log:
140+
- Which files were processed
141+
- The prompts used
142+
- Timestamp of research execution
143+
- Model versions and configurations used
144+
- This logging enables audit trails and debugging while maintaining transparency about AI-generated content.
145+
- ### 6.5. Cost Management
146+
- Deep Research workflows can be expensive due to:
147+
- Multiple LLM calls (planner + writer)
148+
- Search API usage across multiple providers
149+
- Potential long-running research tasks
150+
- Consider implementing:
151+
- Cost alerts via GitHub Actions notifications
152+
- Usage limits per repository or time period
153+
- Optional manual approval gates for expensive operations
154+
- ## 7. Architecture Options Comparison
155+
- ### 7.1. Hosted LangGraph Endpoint
156+
- **Pros:**
157+
- Simplified GitHub Action (just HTTP calls)
158+
- Centralized infrastructure management
159+
- Easier to scale and update
160+
- Can serve multiple repositories
161+
- **Cons:**
162+
- Requires separate hosting infrastructure
163+
- Additional network latency
164+
- Potential single point of failure
165+
- Ongoing hosting costs
166+
- ### 7.2. Self-Hosted Container Runner
167+
- **Pros:**
168+
- Full control over execution environment
169+
- No external service dependencies
170+
- Can run entirely within GitHub Actions
171+
- Lower latency (local execution)
172+
- **Cons:**
173+
- Longer GitHub Action execution time
174+
- Higher resource usage in Actions
175+
- More complex dependency management
176+
- Potential timeout issues for long research tasks
177+
- ### 7.3. Webhook or External MCP Server Orchestrator
178+
- **Pros:**
179+
- Decoupled architecture
180+
- Can integrate with other systems
181+
- More flexible triggering mechanisms
182+
- **Cons:**
183+
- Most complex setup
184+
- Requires additional infrastructure
185+
- More moving parts to maintain
186+
- ## 8. Recommendation for MVP Implementation
187+
- ### 8.1. Easiest Path to Prototype
188+
- For the MVP, recommend the **self-hosted container runner** approach:
189+
1. Use GitHub Actions with Python setup
190+
2. Install OpenDeepResearch dependencies directly in the Action
191+
3. Run research synchronously within the Action
192+
4. Commit results back to the repository
193+
- This approach minimizes infrastructure requirements and allows for rapid iteration. The main limitation is GitHub Actions execution time limits (6 hours for standard plans), which should be sufficient for most research tasks.
194+
- ### 8.2. Scalable Path for Production
195+
- For production use with multiple repositories or high volume:
196+
1. Deploy OpenDeepResearch as a hosted LangGraph endpoint
197+
2. Use GitHub Actions to make HTTP API calls to the endpoint
198+
3. Implement async processing with webhook callbacks for results
199+
4. Add queue management for handling multiple concurrent requests
200+
- This architecture supports better resource management, cost optimization, and scalability.
201+
- ### 8.3. Implementation Phases
202+
- **Phase 1 (MVP):**
203+
- Basic front-matter detection
204+
- Simple OpenDeepResearch invocation
205+
- Basic result appending
206+
- Manual testing with a single repository
207+
- **Phase 2 (Enhanced):**
208+
- Reference to footnote conversion
209+
- Error handling and retries
210+
- Cost monitoring and alerts
211+
- Support for multiple model providers
212+
- **Phase 3 (Production):**
213+
- Hosted endpoint migration
214+
- Async processing with webhooks
215+
- Multi-repository support
216+
- Advanced logging and analytics
217+
- ## 9. Additional Considerations
218+
- ### 9.1. LogSeq-Specific Formatting
219+
- The workflow must ensure results conform to LogSeq Flavored Markdown:
220+
- Use bullet points (`-`) for all content
221+
- Proper heading hierarchy (H1 at root, H2 at first indent, etc.)
222+
- Convert standard markdown footnotes to LogSeq format: `[^1]: url`
223+
- Avoid horizontal rules and ensure proper code block nesting
224+
- ### 9.2. Conflict Resolution
225+
- If a file is modified between research initiation and result commit, the workflow should:
226+
- Detect conflicts
227+
- Either merge results intelligently or
228+
- Fail gracefully with a notification
229+
- ### 9.3. Incremental Updates
230+
- Consider supporting incremental research updates:
231+
- Detect if research results already exist
232+
- Allow re-running research with updated prompts
233+
- Optionally append new findings or replace existing results
234+
- ## Conclusion
235+
- Building a GitHub Action for automated Deep Research with LogSeq integration is feasible using LangChain's OpenDeepResearch. The MVP should use a self-hosted container approach within GitHub Actions for simplicity, with a migration path to a hosted LangGraph endpoint for scalability. Key implementation considerations include proper front-matter parsing, LogSeq Markdown formatting, reference-to-footnote conversion, security best practices for API keys, and cost management. The recommended approach balances ease of implementation with future scalability needs.
236+
- ## Footnotes
237+
- [^1]: https://docs.langchain.com/oss/python/integrations/tools/github
238+
- [^2]: https://blog.langchain.com/gpt-researcher-x-langchain
239+
- [^3]: https://medium.com/@olahsymbo/ai-code-review-agent-built-with-langchain-github-actions-0232dbc48b1c
240+
- [^4]: https://docs.langchain.com/labs/swe/usage/github
241+
- [^5]: https://github.com/langchain-ai/open_deep_research
242+
- [^6]: https://www.edenai.co/
243+
- [^7]: https://openrouter.ai/
244+

0 commit comments

Comments
 (0)