# Hedwig
Hedwig is a research note management system designed for research teams. It synchronizes Notion workspaces to Git repositories for version control and generates AI-powered daily summaries of research activities. The system creates both individual change summaries and team overview summaries with MVP highlights, then distributes them through messaging platforms like Slack.
## Features
- **Notion Synchronization**: Automatically sync research notes from Notion to a Git repository
- **AI-Powered Summaries**: Generate intelligent summaries of research changes using LLMs
- **Team Overviews**: Create consolidated team overviews with MVP highlights
- **Context Plugins**: Add contextual information (weather, calendar events) to overview summaries
- **Multi-Platform Messaging**: Distribute summaries through various messaging platforms (currently Slack)
- **Automated Pipeline**: Run the complete workflow with a single command
- **Flexible Configuration**: Customize prompts, models, and behavior through configuration
## Installation
Install Hedwig from PyPI:
```bash
pip install hedwiglab
```
Or install from source:
```bash
git clone https://github.com/ChangLabSNU/Hedwig
cd Hedwig
pip install -e .
```
## Quick Start
1. **Set up configuration**:
```bash
# Download the example configuration
curl -O https://raw.githubusercontent.com/ChangLabSNU/Hedwig/refs/heads/main/config.yml.example
# Create your config file
cp config.yml.example config.yml
# Edit config.yml with your settings
```
2. **Configure API keys and etc**:
```yaml
# In config.yml
api:
notion:
api_key: 'your-notion-api-key'
llm:
key: 'your-gemini-api-key'
messaging:
slack:
token: 'your-slack-bot-token'
```
3. **Check system health** (recommended before first sync):
```bash
hedwig health --config config.yml
```
This verifies that all components are properly configured and accessible.
4. **Sync Notion content**:
```bash
hedwig sync
```
5. **Run the pipeline**:
```bash
hedwig pipeline
```
## Workflow Overview
Hedwig follows a two-stage process:
```
┌─────────────┐
│ STAGE 1 │
│ Data Update │
└─────────────┘
│
▼
┌─────────────┐
│ hedwig sync │ ─── Fetches latest research notes from Notion
└─────────────┘ and commits them to Git repository
│
│ (Run periodically or on-demand)
│
▼
┌─────────────┐
│ STAGE 2 │
│ Pipeline │
└─────────────┘
│
▼
┌──────────────────────────┐
│ hedwig pipeline │ ─── Automated 3-step process:
└──────────────────────────┘
│
├─► generate-change-summary ─── Analyzes Git commits and creates
│ AI summaries of recent changes
│
├─► generate-overview ──────── Consolidates individual summaries
│ into team-focused overview
│
└─► post-summary ───────────── Posts to messaging platform
(e.g., Slack Canvas)
```
**Important**: The `sync` command must be run before the pipeline to ensure the Git repository has the latest Notion content. The sync is NOT part of the pipeline and should be scheduled separately.
## Commands
### `hedwig health`
Checks the health of all Hedwig components and dependencies. **Recommended to run before first sync** to ensure proper setup.
```bash
hedwig health [--config CONFIG] [--quick] [--json] [--quiet]
```
**Options:**
- `--config`: Configuration file path (default: `config.yml`)
- `--quick`: Skip API connectivity tests for faster results
- `--json`: Output results in JSON format for monitoring tools
- `--quiet`: Suppress informational messages
**Health Checks Include:**
- Configuration file validity and required keys
- Git repository status and permissions
- Python package dependencies
- Filesystem permissions and disk space
- API connectivity (Notion, LLM, Slack) unless `--quick` is used
**Exit Codes:**
- `0`: All checks passed (HEALTHY)
- `1`: Some non-critical checks failed (DEGRADED)
- `2`: Critical checks failed (CRITICAL)
**Example Usage:**
```bash
# Full health check before first sync
hedwig health --config config.yml
# Quick check (skip API tests)
hedwig health --quick
# JSON output for monitoring
hedwig health --json | jq '.overall_status'
```
### `hedwig sync`
Synchronizes Notion pages to a Git repository.
```bash
hedwig sync [--config CONFIG] [--quiet] [--verbose]
```
**Options:**
- `--config`: Configuration file path (default: `config.yml`)
- `--quiet`: Suppress progress messages
- `--verbose`: Show detailed debug output
### `hedwig sync-userlist`
Manually syncs user list from Notion and saves to TSV file. This command is typically not needed in regular workflows as it's automatically triggered when unknown users are encountered.
```bash
hedwig sync-userlist [--config CONFIG] [--quiet]
```
**Options:**
- `--config`: Configuration file path (default: `config.yml`)
- `--quiet`: Suppress progress messages
**Output:**
Creates a TSV file at the path specified in `paths.userlist_file` containing:
- `user_id`: Notion user UUID
- `name`: User's display name
**Override Feature:**
If `paths.userlist_override_file` is configured and the file exists, users from this file will override or supplement the Notion user list. This is useful for:
- Correcting names that appear incorrectly in Notion
- Adding custom display names for specific users
- Including users that may not be in the Notion workspace
The override file should have the same TSV format as the output file.
**Note:** With auto-sync enabled (default), this command is automatically run when `generate-change-summary` encounters unknown user IDs.
### `hedwig generate-change-summary`
Analyzes recent Git commits and generates AI-powered summaries.
```bash
hedwig generate-change-summary [--config CONFIG] [--no-write]
```
**Options:**
- `--config`: Configuration file path (default: `config.yml`)
- `--no-write`: Print to stdout instead of saving to file
**Auto User Sync:**
When `change_summary.auto_sync_userlist` is set to `true` (default), the command will automatically run `sync-userlist` if it encounters user IDs not found in the user list. This ensures that new team members are automatically added to the user list. Set to `false` to disable this behavior.
### `hedwig generate-overview`
Creates team-focused overview summaries from individual change summaries.
```bash
hedwig generate-overview [--config CONFIG] [--no-write]
```
**Options:**
- `--config`: Configuration file path (default: `config.yml`)
- `--no-write`: Print to stdout instead of saving to file
### `hedwig post-summary`
Posts summaries to configured messaging platforms.
```bash
hedwig post-summary --summary-file FILE --overview-file FILE --title TITLE [--config CONFIG]
```
**Options:**
- `--summary-file`: Path to the markdown summary file
- `--overview-file`: Path to the overview message file
- `--title`: Title for the posted summary
- `--config`: Configuration file path (default: `config.yml`)
### `hedwig pipeline`
Runs the complete summarization pipeline automatically.
```bash
hedwig pipeline [--config CONFIG]
```
**Options:**
- `--config`: Configuration file path (default: `config.yml`)
**Note**: This command does NOT include syncing from Notion. Run `hedwig sync` separately before the pipeline to ensure the Git repository is up-to-date.
## Configuration
Hedwig uses a YAML configuration file. Download the example configuration and customize:
```bash
curl -O https://raw.githubusercontent.com/ChangLabSNU/Hedwig/refs/heads/main/config.yml.example
cp config.yml.example config.yml
```
### Essential Settings
```yaml
# Repository paths
paths:
notes_repository: '/path/to/your/notes/repo'
change_summary_output: '/path/to/summary/output'
# API Keys (can be set here OR as environment variables)
notion:
api_key: 'your-notion-api-key' # Alternative: export NOTION_API_KEY=...
api:
llm:
key: 'your-gemini-api-key' # Alternative: export GEMINI_API_KEY=...
url: 'https://generativelanguage.googleapis.com/v1beta/openai/'
messaging:
slack:
token: 'xoxb-your-bot-token' # Alternative: export SLACK_TOKEN=...
```
### Key Configuration Options
- **Sync Settings**: Checkpoint tracking, timezone, lookback days
- **Summary Settings**: Model selection, prompt customization, diff length limits
- **Overview Settings**: Language selection, lab information, weekday configurations
- **Messaging Settings**: Platform selection, channel configuration
- **Pipeline Settings**: Title format customization
See `config.yml.example` for all available options with detailed comments.
## Automated Execution
Set up cron jobs for the two-stage process:
```bash
# Sync from Notion every hour during work hours
0 * * * * /usr/bin/hedwig sync --config /path/to/config.yml
# Run pipeline everyday except Sunday at 8:30 AM
30 8 * * 1-6 /usr/bin/hedwig pipeline --config /path/to/config.yml
```
## Messaging Platforms
### Slack Integration
Hedwig creates Canvas documents in Slack for rich formatting:
1. Create a Slack app with required permissions:
- `channels:read`
- `chat:write`
- `canvases:write`
- `canvases:read`
2. Install the app to your workspace
3. Configure in `config.yml`:
```yaml
messaging:
active: slack
slack:
token: 'xoxb-your-bot-token'
channel_id: 'C12345678'
```
## Advanced Usage
### Custom Prompts
Customize LLM prompts for summaries:
```yaml
api:
llm:
diff_summary_prompt: |
Your custom prompt for analyzing diffs...
overview_prompt_template: |
Your custom overview template with {summary_range} and {forthcoming_range}...
# Customize how context information is introduced in the prompt
overview_context_information_prefix: |
Use the following context information minimally only at the appropriate places in the summary, and do not repeat the context information verbatim.
```
### Changing Language
Set overview language and customize instructions:
```yaml
overview:
language: en # Options: ko, en, ja, zh_CN
lab_info: "Your Lab Name and Description"
```
### Context Plugins
Context plugins provide additional contextual information in overview summaries. This helps the AI generate more relevant and timely summaries by providing context about current conditions.
#### Date Plugin
Provides the current date and weekday:
```yaml
overview:
context_plugins:
date:
enabled: true
```
Outputs: `Today: 2025-07-19 (Friday)`
This simple plugin helps the AI understand what day it is when generating summaries, which can be useful for contextual references.
#### Static Plugin
Provides fixed context information that remains constant across all summaries. Perfect for laboratory-specific information:
```yaml
overview:
context_plugins:
static:
enabled: true
content: |
Laboratory: Computational Biology Lab
Research Areas: Genomics, RNA Biology, Bioinformatics
Current Projects:
- Single-cell RNA sequencing analysis
- Alternative splicing in cancer
- Long-read sequencing methods
Team Members:
- Dr. Jane Smith (PI) - Computational genomics
- Dr. John Doe - Machine learning for biology
- Alice Johnson - RNA-seq analysis
- Bob Wilson - Proteomics integration
```
**Use cases:**
- Laboratory information and research focus
- Current research topics and projects
- Team member list and expertise
- Laboratory policies or guidelines
- Any other static context that helps AI generate better summaries
The content is passed directly to the LLM without modification, allowing full control over the formatting and information structure.
#### Weather Plugin
Adds weather information to the overview prompt:
```yaml
overview:
context_plugins:
weather:
enabled: true
latitude: 37.5665 # Your location's latitude
longitude: 126.9780 # Your location's longitude
city_name: Seoul # Display name for the location
```
The weather plugin fetches data from Open-Meteo API and includes:
- Yesterday's weather
- Today's weather
- Tomorrow's weather forecast
#### Calendar Plugin
Adds calendar events to provide context about holidays, meetings, or important dates:
```yaml
overview:
context_plugins:
calendar:
enabled: true
days_before: 1 # Include events from 1 day ago (0 = today only)
days_after: 7 # Include events up to 7 days ahead
calendars:
# iCal example (public calendars)
- name: Korean Holidays
type: ical
url: https://calendar.google.com/calendar/ical/ko.south_korea%23holiday%40group.v.calendar.google.com/public/basic.ics
enabled: true
# CalDAV example (private calendars, requires authentication)
- name: Team Calendar
type: caldav
url: https://nextcloud.example.com/remote.php/dav/
username: your-username # Or use env var CALDAV_USERNAME
password: your-password # Or use env var CALDAV_PASSWORD
calendar_url: https://nextcloud.example.com/remote.php/dav/calendars/user/personal/ # Optional
enabled: true
```
**Features:**
- Supports both iCal (public) and CalDAV (private) calendars
- Multiple calendars can be configured
- Events are grouped by time periods (today, this week, next week, later)
- Calendars with no events are automatically suppressed from output
- CalDAV requires `pip install caldav` for authentication support
#### Custom Context Plugins
You can create custom context plugins by:
1. Creating a new Python file in `Hedwig/overview/context_plugins/`
2. Inheriting from `ContextPlugin` base class
3. Implementing the required methods:
- `name` property: Unique identifier for your plugin
- `get_context()` method: Returns the context string or None
Example custom plugin structure:
```python
from .base import ContextPlugin
from .registry import ContextPluginRegistry
class MyCustomPlugin(ContextPlugin):
@property
def name(self) -> str:
return "custom"
def get_context(self) -> Optional[str]:
if not self.is_enabled():
return None
# Your logic here
return "Your context information"
# Register the plugin
ContextPluginRegistry.register("custom", MyCustomPlugin)
```
## Troubleshooting
### Common Issues
1. **Configuration problems**: Run `hedwig health` to diagnose configuration issues
2. **No summaries generated**: Check if there are recent commits within the lookback period
3. **Sync failures**: Verify Notion API key and page permissions
4. **LLM errors**: Check API key and rate limits
5. **Messaging failures**: Verify bot token and channel permissions
### First-Time Setup Issues
If you encounter problems during initial setup, run the health check:
```bash
hedwig health --config config.yml
```
This will identify:
- Missing or invalid configuration
- Permission issues
- Missing dependencies
- API connectivity problems
### Debug Mode
Run with verbose output for troubleshooting:
```bash
hedwig pipeline --config config.yml --verbose
```
### Logs
Check application logs for detailed error messages. The location depends on your configuration.
## License
MIT License - see LICENSE.txt for details
## Author
Hyeshik Chang <hyeshik@snu.ac.kr>
Raw data
{
"_id": null,
"home_page": null,
"name": "HedwigLab",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "notion, research, lab-management, sync, ai-summary, llm, slack, team-collaboration",
"author": null,
"author_email": "Hyeshik Chang <hyeshik@snu.ac.kr>",
"download_url": "https://files.pythonhosted.org/packages/fc/50/ce92b3ca3ab252f5a9aa7470e600e77e6f286df9aa336c09ecf21a418ef7/hedwiglab-1.0.0.tar.gz",
"platform": null,
"description": "# Hedwig\n\nHedwig is a research note management system designed for research teams. It synchronizes Notion workspaces to Git repositories for version control and generates AI-powered daily summaries of research activities. The system creates both individual change summaries and team overview summaries with MVP highlights, then distributes them through messaging platforms like Slack.\n\n## Features\n\n- **Notion Synchronization**: Automatically sync research notes from Notion to a Git repository\n- **AI-Powered Summaries**: Generate intelligent summaries of research changes using LLMs\n- **Team Overviews**: Create consolidated team overviews with MVP highlights\n- **Context Plugins**: Add contextual information (weather, calendar events) to overview summaries\n- **Multi-Platform Messaging**: Distribute summaries through various messaging platforms (currently Slack)\n- **Automated Pipeline**: Run the complete workflow with a single command\n- **Flexible Configuration**: Customize prompts, models, and behavior through configuration\n\n## Installation\n\nInstall Hedwig from PyPI:\n\n```bash\npip install hedwiglab\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/ChangLabSNU/Hedwig\ncd Hedwig\npip install -e .\n```\n\n## Quick Start\n\n1. **Set up configuration**:\n ```bash\n # Download the example configuration\n curl -O https://raw.githubusercontent.com/ChangLabSNU/Hedwig/refs/heads/main/config.yml.example\n\n # Create your config file\n cp config.yml.example config.yml\n\n # Edit config.yml with your settings\n ```\n\n2. **Configure API keys and etc**:\n ```yaml\n # In config.yml\n api:\n notion:\n api_key: 'your-notion-api-key'\n llm:\n key: 'your-gemini-api-key'\n messaging:\n slack:\n token: 'your-slack-bot-token'\n ```\n\n3. **Check system health** (recommended before first sync):\n ```bash\n hedwig health --config config.yml\n ```\n This verifies that all components are properly configured and accessible.\n\n4. **Sync Notion content**:\n ```bash\n hedwig sync\n ```\n\n5. **Run the pipeline**:\n ```bash\n hedwig pipeline\n ```\n\n## Workflow Overview\n\nHedwig follows a two-stage process:\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 STAGE 1 \u2502\n\u2502 Data Update \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502\n \u25bc\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 hedwig sync \u2502 \u2500\u2500\u2500 Fetches latest research notes from Notion\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 and commits them to Git repository\n \u2502\n \u2502 (Run periodically or on-demand)\n \u2502\n \u25bc\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 STAGE 2 \u2502\n\u2502 Pipeline \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502\n \u25bc\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 hedwig pipeline \u2502 \u2500\u2500\u2500 Automated 3-step process:\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502\n \u251c\u2500\u25ba generate-change-summary \u2500\u2500\u2500 Analyzes Git commits and creates\n \u2502 AI summaries of recent changes\n \u2502\n \u251c\u2500\u25ba generate-overview \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 Consolidates individual summaries\n \u2502 into team-focused overview\n \u2502\n \u2514\u2500\u25ba post-summary \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 Posts to messaging platform\n (e.g., Slack Canvas)\n```\n\n**Important**: The `sync` command must be run before the pipeline to ensure the Git repository has the latest Notion content. The sync is NOT part of the pipeline and should be scheduled separately.\n\n## Commands\n\n### `hedwig health`\nChecks the health of all Hedwig components and dependencies. **Recommended to run before first sync** to ensure proper setup.\n\n```bash\nhedwig health [--config CONFIG] [--quick] [--json] [--quiet]\n```\n\n**Options:**\n- `--config`: Configuration file path (default: `config.yml`)\n- `--quick`: Skip API connectivity tests for faster results\n- `--json`: Output results in JSON format for monitoring tools\n- `--quiet`: Suppress informational messages\n\n**Health Checks Include:**\n- Configuration file validity and required keys\n- Git repository status and permissions\n- Python package dependencies\n- Filesystem permissions and disk space\n- API connectivity (Notion, LLM, Slack) unless `--quick` is used\n\n**Exit Codes:**\n- `0`: All checks passed (HEALTHY)\n- `1`: Some non-critical checks failed (DEGRADED)\n- `2`: Critical checks failed (CRITICAL)\n\n**Example Usage:**\n```bash\n# Full health check before first sync\nhedwig health --config config.yml\n\n# Quick check (skip API tests)\nhedwig health --quick\n\n# JSON output for monitoring\nhedwig health --json | jq '.overall_status'\n```\n\n### `hedwig sync`\nSynchronizes Notion pages to a Git repository.\n\n```bash\nhedwig sync [--config CONFIG] [--quiet] [--verbose]\n```\n\n**Options:**\n- `--config`: Configuration file path (default: `config.yml`)\n- `--quiet`: Suppress progress messages\n- `--verbose`: Show detailed debug output\n\n### `hedwig sync-userlist`\nManually syncs user list from Notion and saves to TSV file. This command is typically not needed in regular workflows as it's automatically triggered when unknown users are encountered.\n\n```bash\nhedwig sync-userlist [--config CONFIG] [--quiet]\n```\n\n**Options:**\n- `--config`: Configuration file path (default: `config.yml`)\n- `--quiet`: Suppress progress messages\n\n**Output:**\nCreates a TSV file at the path specified in `paths.userlist_file` containing:\n- `user_id`: Notion user UUID\n- `name`: User's display name\n\n**Override Feature:**\nIf `paths.userlist_override_file` is configured and the file exists, users from this file will override or supplement the Notion user list. This is useful for:\n- Correcting names that appear incorrectly in Notion\n- Adding custom display names for specific users\n- Including users that may not be in the Notion workspace\n\nThe override file should have the same TSV format as the output file.\n\n**Note:** With auto-sync enabled (default), this command is automatically run when `generate-change-summary` encounters unknown user IDs.\n\n### `hedwig generate-change-summary`\nAnalyzes recent Git commits and generates AI-powered summaries.\n\n```bash\nhedwig generate-change-summary [--config CONFIG] [--no-write]\n```\n\n**Options:**\n- `--config`: Configuration file path (default: `config.yml`)\n- `--no-write`: Print to stdout instead of saving to file\n\n**Auto User Sync:**\nWhen `change_summary.auto_sync_userlist` is set to `true` (default), the command will automatically run `sync-userlist` if it encounters user IDs not found in the user list. This ensures that new team members are automatically added to the user list. Set to `false` to disable this behavior.\n\n### `hedwig generate-overview`\nCreates team-focused overview summaries from individual change summaries.\n\n```bash\nhedwig generate-overview [--config CONFIG] [--no-write]\n```\n\n**Options:**\n- `--config`: Configuration file path (default: `config.yml`)\n- `--no-write`: Print to stdout instead of saving to file\n\n### `hedwig post-summary`\nPosts summaries to configured messaging platforms.\n\n```bash\nhedwig post-summary --summary-file FILE --overview-file FILE --title TITLE [--config CONFIG]\n```\n\n**Options:**\n- `--summary-file`: Path to the markdown summary file\n- `--overview-file`: Path to the overview message file\n- `--title`: Title for the posted summary\n- `--config`: Configuration file path (default: `config.yml`)\n\n### `hedwig pipeline`\nRuns the complete summarization pipeline automatically.\n\n```bash\nhedwig pipeline [--config CONFIG]\n```\n\n**Options:**\n- `--config`: Configuration file path (default: `config.yml`)\n\n**Note**: This command does NOT include syncing from Notion. Run `hedwig sync` separately before the pipeline to ensure the Git repository is up-to-date.\n\n## Configuration\n\nHedwig uses a YAML configuration file. Download the example configuration and customize:\n\n```bash\ncurl -O https://raw.githubusercontent.com/ChangLabSNU/Hedwig/refs/heads/main/config.yml.example\ncp config.yml.example config.yml\n```\n\n### Essential Settings\n\n```yaml\n# Repository paths\npaths:\n notes_repository: '/path/to/your/notes/repo'\n change_summary_output: '/path/to/summary/output'\n\n# API Keys (can be set here OR as environment variables)\nnotion:\n api_key: 'your-notion-api-key' # Alternative: export NOTION_API_KEY=...\n\napi:\n llm:\n key: 'your-gemini-api-key' # Alternative: export GEMINI_API_KEY=...\n url: 'https://generativelanguage.googleapis.com/v1beta/openai/'\n\nmessaging:\n slack:\n token: 'xoxb-your-bot-token' # Alternative: export SLACK_TOKEN=...\n```\n\n### Key Configuration Options\n\n- **Sync Settings**: Checkpoint tracking, timezone, lookback days\n- **Summary Settings**: Model selection, prompt customization, diff length limits\n- **Overview Settings**: Language selection, lab information, weekday configurations\n- **Messaging Settings**: Platform selection, channel configuration\n- **Pipeline Settings**: Title format customization\n\nSee `config.yml.example` for all available options with detailed comments.\n\n## Automated Execution\n\nSet up cron jobs for the two-stage process:\n\n```bash\n# Sync from Notion every hour during work hours\n0 * * * * /usr/bin/hedwig sync --config /path/to/config.yml\n\n# Run pipeline everyday except Sunday at 8:30 AM\n30 8 * * 1-6 /usr/bin/hedwig pipeline --config /path/to/config.yml\n```\n\n## Messaging Platforms\n\n### Slack Integration\n\nHedwig creates Canvas documents in Slack for rich formatting:\n\n1. Create a Slack app with required permissions:\n - `channels:read`\n - `chat:write`\n - `canvases:write`\n - `canvases:read`\n\n2. Install the app to your workspace\n\n3. Configure in `config.yml`:\n ```yaml\n messaging:\n active: slack\n slack:\n token: 'xoxb-your-bot-token'\n channel_id: 'C12345678'\n ```\n\n## Advanced Usage\n\n### Custom Prompts\n\nCustomize LLM prompts for summaries:\n\n```yaml\napi:\n llm:\n diff_summary_prompt: |\n Your custom prompt for analyzing diffs...\n\n overview_prompt_template: |\n Your custom overview template with {summary_range} and {forthcoming_range}...\n \n # Customize how context information is introduced in the prompt\n overview_context_information_prefix: |\n Use the following context information minimally only at the appropriate places in the summary, and do not repeat the context information verbatim.\n```\n\n### Changing Language\n\nSet overview language and customize instructions:\n\n```yaml\noverview:\n language: en # Options: ko, en, ja, zh_CN\n lab_info: \"Your Lab Name and Description\"\n```\n\n### Context Plugins\n\nContext plugins provide additional contextual information in overview summaries. This helps the AI generate more relevant and timely summaries by providing context about current conditions.\n\n#### Date Plugin\n\nProvides the current date and weekday:\n\n```yaml\noverview:\n context_plugins:\n date:\n enabled: true\n```\n\nOutputs: `Today: 2025-07-19 (Friday)`\n\nThis simple plugin helps the AI understand what day it is when generating summaries, which can be useful for contextual references.\n\n#### Static Plugin\n\nProvides fixed context information that remains constant across all summaries. Perfect for laboratory-specific information:\n\n```yaml\noverview:\n context_plugins:\n static:\n enabled: true\n content: |\n Laboratory: Computational Biology Lab\n Research Areas: Genomics, RNA Biology, Bioinformatics\n Current Projects:\n - Single-cell RNA sequencing analysis\n - Alternative splicing in cancer\n - Long-read sequencing methods\n Team Members:\n - Dr. Jane Smith (PI) - Computational genomics\n - Dr. John Doe - Machine learning for biology\n - Alice Johnson - RNA-seq analysis\n - Bob Wilson - Proteomics integration\n```\n\n**Use cases:**\n- Laboratory information and research focus\n- Current research topics and projects\n- Team member list and expertise\n- Laboratory policies or guidelines\n- Any other static context that helps AI generate better summaries\n\nThe content is passed directly to the LLM without modification, allowing full control over the formatting and information structure.\n\n#### Weather Plugin\n\nAdds weather information to the overview prompt:\n\n```yaml\noverview:\n context_plugins:\n weather:\n enabled: true\n latitude: 37.5665 # Your location's latitude\n longitude: 126.9780 # Your location's longitude\n city_name: Seoul # Display name for the location\n```\n\nThe weather plugin fetches data from Open-Meteo API and includes:\n- Yesterday's weather\n- Today's weather\n- Tomorrow's weather forecast\n\n#### Calendar Plugin\n\nAdds calendar events to provide context about holidays, meetings, or important dates:\n\n```yaml\noverview:\n context_plugins:\n calendar:\n enabled: true\n days_before: 1 # Include events from 1 day ago (0 = today only)\n days_after: 7 # Include events up to 7 days ahead\n calendars:\n # iCal example (public calendars)\n - name: Korean Holidays\n type: ical\n url: https://calendar.google.com/calendar/ical/ko.south_korea%23holiday%40group.v.calendar.google.com/public/basic.ics\n enabled: true\n \n # CalDAV example (private calendars, requires authentication)\n - name: Team Calendar\n type: caldav\n url: https://nextcloud.example.com/remote.php/dav/\n username: your-username # Or use env var CALDAV_USERNAME\n password: your-password # Or use env var CALDAV_PASSWORD\n calendar_url: https://nextcloud.example.com/remote.php/dav/calendars/user/personal/ # Optional\n enabled: true\n```\n\n**Features:**\n- Supports both iCal (public) and CalDAV (private) calendars\n- Multiple calendars can be configured\n- Events are grouped by time periods (today, this week, next week, later)\n- Calendars with no events are automatically suppressed from output\n- CalDAV requires `pip install caldav` for authentication support\n\n#### Custom Context Plugins\n\nYou can create custom context plugins by:\n\n1. Creating a new Python file in `Hedwig/overview/context_plugins/`\n2. Inheriting from `ContextPlugin` base class\n3. Implementing the required methods:\n - `name` property: Unique identifier for your plugin\n - `get_context()` method: Returns the context string or None\n\nExample custom plugin structure:\n```python\nfrom .base import ContextPlugin\nfrom .registry import ContextPluginRegistry\n\nclass MyCustomPlugin(ContextPlugin):\n @property\n def name(self) -> str:\n return \"custom\"\n \n def get_context(self) -> Optional[str]:\n if not self.is_enabled():\n return None\n # Your logic here\n return \"Your context information\"\n\n# Register the plugin\nContextPluginRegistry.register(\"custom\", MyCustomPlugin)\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Configuration problems**: Run `hedwig health` to diagnose configuration issues\n2. **No summaries generated**: Check if there are recent commits within the lookback period\n3. **Sync failures**: Verify Notion API key and page permissions\n4. **LLM errors**: Check API key and rate limits\n5. **Messaging failures**: Verify bot token and channel permissions\n\n### First-Time Setup Issues\n\nIf you encounter problems during initial setup, run the health check:\n\n```bash\nhedwig health --config config.yml\n```\n\nThis will identify:\n- Missing or invalid configuration\n- Permission issues\n- Missing dependencies\n- API connectivity problems\n\n### Debug Mode\n\nRun with verbose output for troubleshooting:\n\n```bash\nhedwig pipeline --config config.yml --verbose\n```\n\n### Logs\n\nCheck application logs for detailed error messages. The location depends on your configuration.\n\n## License\n\nMIT License - see LICENSE.txt for details\n\n## Author\n\nHyeshik Chang <hyeshik@snu.ac.kr>\n",
"bugtrack_url": null,
"license": null,
"summary": "Research note management system with Notion sync and AI-powered team summaries",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/ChangLabSNU/Hedwig/issues",
"Documentation": "https://github.com/ChangLabSNU/Hedwig#readme",
"Homepage": "https://github.com/ChangLabSNU/Hedwig",
"Source Code": "https://github.com/ChangLabSNU/Hedwig"
},
"split_keywords": [
"notion",
" research",
" lab-management",
" sync",
" ai-summary",
" llm",
" slack",
" team-collaboration"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0ef869b44a8aa28460b7b4a97a732c6807d37e51aa7f811484c0c55c1ff6a9c7",
"md5": "95fe62c533c28852c0358389bb3f4a9a",
"sha256": "2a1de1fded0e8a2069ad419756cc20c6fe107e1e7f05da11e5bce9db4b39a457"
},
"downloads": -1,
"filename": "hedwiglab-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "95fe62c533c28852c0358389bb3f4a9a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 88684,
"upload_time": "2025-07-21T04:23:37",
"upload_time_iso_8601": "2025-07-21T04:23:37.297261Z",
"url": "https://files.pythonhosted.org/packages/0e/f8/69b44a8aa28460b7b4a97a732c6807d37e51aa7f811484c0c55c1ff6a9c7/hedwiglab-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fc50ce92b3ca3ab252f5a9aa7470e600e77e6f286df9aa336c09ecf21a418ef7",
"md5": "4e9ea1c5b390ccb467d11c09790dac00",
"sha256": "cb05269004a0623735fd1f526e7513683a431c0dfe7fcb94d40adf5204c92a93"
},
"downloads": -1,
"filename": "hedwiglab-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "4e9ea1c5b390ccb467d11c09790dac00",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 66340,
"upload_time": "2025-07-21T04:23:39",
"upload_time_iso_8601": "2025-07-21T04:23:39.949457Z",
"url": "https://files.pythonhosted.org/packages/fc/50/ce92b3ca3ab252f5a9aa7470e600e77e6f286df9aa336c09ecf21a418ef7/hedwiglab-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-21 04:23:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ChangLabSNU",
"github_project": "Hedwig",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "hedwiglab"
}
JSON
