ccal 0.1.4__tar.gz

ccal-0.1.4/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish Python Package
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  pypi-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ccal-0.1.4/.gitignore

@@ -0,0 +1,39 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+
+# Testing / Coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Generated ICS files
+*.ics
+
+# Local Google OAuth files
+google_credentials.json
+google_cresntials.json
+google_token_*.json
+
+# local image test folder
+.imgs/

ccal-0.1.4/.python-version

@@ -0,0 +1 @@
+3.12

ccal-0.1.4/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: ccal
+Version: 0.1.4
+Summary: CLI tool for adding calendar events
+Requires-Python: >=3.12
+Requires-Dist: google-api-python-client>=2.0
+Requires-Dist: google-auth-oauthlib>=1.0
+Requires-Dist: icalendar>=6.0
+Requires-Dist: keyring>=25.0
+Requires-Dist: litellm>=1.0
+Requires-Dist: pydantic>=2.13.1
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.24.1
+Provides-Extra: ocr
+Requires-Dist: pillow>=11.0; extra == 'ocr'
+Requires-Dist: pytesseract>=0.3.13; extra == 'ocr'
+Description-Content-Type: text/markdown
+
+# ccal
+
+[中文文档](README-zh_cn.md)
+
+A CLI tool that turns natural language text or images into calendar events. Powered by LLMs.
+
+## Features
+
+- **Text input** — describe an event in plain language, ccal parses it into structured fields
+- **Image input** — extract text from screenshots/photos via OCR, then parse
+- **Multi-LLM support** — works with OpenAI, Anthropic, Gemini, OpenRouter, Deepseek, Groq, Mistral, and more (via [litellm](https://github.com/BerriAI/litellm))
+- **ICS export** — generate standard `.ics` files importable by any calendar app
+- **Google Calendar sync** — create events directly on Google Calendar via API
+- **Apple Calendar sync** — add events via AppleScript (macOS only, auto-fallback to ICS on other platforms)
+- **Secure key storage** — API keys stored in your system keyring, never in plain text
+- **Geolocation** — auto-detect timezone and location for accurate event scheduling
+- **Stdin support** — pipe text from other commands
+
+## Requirements
+
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+- [Tesseract OCR](https://github.com/tesseract-ocr/tesseract) (for image input)
+
+## Installation
+
+```bash
+git clone https://github.com/your-username/ccal.git
+cd ccal
+uv sync
+```
+
+## Quick Start
+
+### 1. Setup
+
+```bash
+ccal setup
+```
+
+This will walk you through configuring:
+- LLM provider and model
+- API key (stored securely in system keyring)
+- Default output method (ICS file, Google Calendar, or Apple Calendar)
+- Google Calendar setup, including client type, auth mode, credentials location, and Calendar ID
+
+### 2. Add an event
+
+From text:
+
+```bash
+ccal add "Team meeting tomorrow at 3pm in Conference Room A"
+```
+
+From an image:
+
+```bash
+ccal add flyer.png
+```
+
+From stdin:
+
+```bash
+echo "Lunch with Alice Friday noon" | ccal add
+```
+
+With options:
+
+```bash
+ccal add "Dinner Friday 7pm at Luigi's" -o google       # sync to Google Calendar
+ccal add "Weekly standup Mon 9am" -o apple               # add to Apple Calendar (macOS)
+ccal add "Weekly standup Mon 9am" -o ics                  # export as .ics file
+ccal add "会议明天下午两点" -m anthropic/claude-sonnet-4-20250514  # use a specific model
+ccal add screenshot.png -l chi_sim                        # OCR with Chinese language
+ccal add "Demo at 2pm" -y                                 # skip confirmation
+ccal add "Demo at 2pm" --json                             # output as JSON
+```
+
+### 3. Parse only (no save)
+
+```bash
+ccal parse "Workshop next Wednesday 10am-12pm, Room 301"
+ccal parse "下周一上午10点团队周会" --json
+```
+
+### 4. View config
+
+```bash
+ccal config
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `ccal add [text\|image]` | Parse input and create a calendar event |
+| `ccal parse [text\|image]` | Parse and display event fields without saving |
+| `ccal setup` | Interactive configuration wizard |
+| `ccal config` | Show current configuration and platform info |
+
+### `ccal add` options
+
+| Option | Description |
+|--------|-------------|
+| `-o`, `--output` | Output method: `ics`, `google`, or `apple` |
+| `-p`, `--provider` | LLM provider name |
+| `-m`, `--model` | LLM model (e.g. `openai/gpt-4o`) |
+| `-y`, `--yes` | Skip confirmation, output directly |
+| `-l`, `--language` | OCR language (e.g. `chi_sim`, `eng+chi_sim`) |
+| `--json` | Output parsed event as JSON |
+
+## Platform Support
+
+| Feature | macOS | Linux | Windows |
+|---------|-------|-------|---------|
+| ICS export | ✅ | ✅ | ✅ |
+| Google Calendar | ✅ | ✅ | ✅ |
+| Apple Calendar | ✅ | ❌ fallback to ICS | ❌ fallback to ICS |
+
+## Configuration
+
+Config is stored at `~/.config/ccal/config.toml`. API keys are stored in your system's native keyring (macOS Keychain / Linux Secret Service / Windows Credential Locker).
+
+For Google Calendar integration, ccal uses two different local files:
+
+- `google_credentials.json`: the OAuth client credentials JSON downloaded from Google Cloud Console. This contains the client id and client secret. Keep this file around after setup.
+- `google_token_*.json`: the cached login token created after the first successful authorization. The access token inside can expire and refresh automatically, so you usually do not need to touch it. ccal picks the cache file based on the current credentials path and auth mode.
+
+During `ccal setup`, place the credentials JSON in the configured directory, or point setup directly at the JSON file. The setup tutorial also explains:
+
+- `Desktop app` vs `TVs and Limited Input devices`
+- `External` vs `Internal`
+- `Testing` status and `Test users`
+- how to find a Google Calendar ID
+- setup-time validation of the selected Calendar ID
+
+You can also configure Google Calendar during `ccal setup` through the dedicated middle step, even if your default output is not Google.
+
+## Project Structure
+
+```
+src/
+├── main.py                  # CLI entry point (Typer)
+├── config.py                # Configuration & keyring management
+├── models/
+│   ├── model.py             # CalendarEvent Pydantic model
+│   └── llm.py               # LLM parsing via litellm
+├── input/
+│   ├── ocr.py               # Image text extraction (pytesseract)
+│   └── geo.py               # IP-based geolocation for timezone
+└── connections/
+    ├── google_calendar.py   # Google Calendar API integration
+    ├── apple_calendar.py    # Apple Calendar via AppleScript (macOS)
+    └── ics.py               # ICS file export
+```
+
+## License
+
+MIT

ccal-0.1.4/README-zh_cn.md

@@ -0,0 +1,159 @@
+# ccal
+
+[English](README.md)
+
+一个命令行工具，将自然语言文本或图片转换为日历事件。由 LLM 驱动。
+
+## 功能特性
+
+- **文本输入** — 用自然语言描述事件，ccal 自动解析为结构化字段
+- **图片输入** — 通过 OCR 从截图/照片中提取文字，再进行解析
+- **多 LLM 支持** — 支持 OpenAI、Anthropic、Gemini、OpenRouter、Deepseek、Groq、Mistral 等（通过 [litellm](https://github.com/BerriAI/litellm)）
+- **ICS 导出** — 生成标准 `.ics` 文件，可被任何日历应用导入
+- **Google 日历同步** — 通过 API 直接在 Google Calendar 创建事件
+- **Apple 日历同步** — 通过 AppleScript 添加事件（仅 macOS，其他平台自动降级为 ICS）
+- **安全密钥存储** — API key 存储在系统原生密钥链中，不以明文保存
+- **地理定位** — 自动检测时区和位置，确保事件时间准确
+- **管道输入** — 支持从其他命令管道传入文本
+
+## 环境要求
+
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/)（推荐）或 pip
+- [Tesseract OCR](https://github.com/tesseract-ocr/tesseract)（图片输入需要）
+
+## 安装
+
+```bash
+git clone https://github.com/your-username/ccal.git
+cd ccal
+uv sync
+```
+
+## 快速开始
+
+### 1. 初始配置
+
+```bash
+ccal setup
+```
+
+将引导你配置：
+- LLM 提供商和模型
+- API key（安全存储在系统密钥链中）
+- 默认输出方式（ICS 文件、Google 日历或 Apple 日历）
+- Google 日历配置，包括客户端类型、鉴权模式、凭据位置和 Calendar ID
+
+### 2. 添加事件
+
+文本输入：
+
+```bash
+ccal add "明天下午3点在会议室A开团队会议"
+```
+
+图片输入：
+
+```bash
+ccal add flyer.png
+```
+
+管道输入：
+
+```bash
+echo "周五中午和 Alice 吃饭" | ccal add
+```
+
+更多选项：
+
+```bash
+ccal add "周五晚上7点在 Luigi's 餐厅聚餐" -o google       # 同步到 Google 日历
+ccal add "每周一早上9点站会" -o apple                       # 添加到 Apple 日历 (macOS)
+ccal add "每周一早上9点站会" -o ics                          # 导出为 .ics 文件
+ccal add "Meeting tomorrow at 2pm" -m anthropic/claude-sonnet-4-20250514  # 指定模型
+ccal add screenshot.png -l chi_sim                          # 使用中文 OCR
+ccal add "下午2点演示" -y                                    # 跳过确认
+ccal add "下午2点演示" --json                                # JSON 格式输出
+```
+
+### 3. 仅解析（不保存）
+
+```bash
+ccal parse "下周三上午10点到12点，301会议室，技术研讨会"
+ccal parse "下周一上午10点团队周会" --json
+```
+
+### 4. 查看配置
+
+```bash
+ccal config
+```
+
+## 命令列表
+
+| 命令 | 说明 |
+|------|------|
+| `ccal add [文本\|图片]` | 解析输入并创建日历事件 |
+| `ccal parse [文本\|图片]` | 解析并展示事件字段，不保存 |
+| `ccal setup` | 交互式配置向导 |
+| `ccal config` | 查看当前配置和平台信息 |
+
+### `ccal add` 选项
+
+| 选项 | 说明 |
+|------|------|
+| `-o`, `--output` | 输出方式：`ics`、`google` 或 `apple` |
+| `-p`, `--provider` | LLM 提供商名称 |
+| `-m`, `--model` | LLM 模型（如 `openai/gpt-4o`） |
+| `-y`, `--yes` | 跳过确认，直接输出 |
+| `-l`, `--language` | OCR 语言（如 `chi_sim`、`eng+chi_sim`） |
+| `--json` | 以 JSON 格式输出解析结果 |
+
+## 平台支持
+
+| 功能 | macOS | Linux | Windows |
+|------|-------|-------|---------|
+| ICS 导出 | ✅ | ✅ | ✅ |
+| Google 日历 | ✅ | ✅ | ✅ |
+| Apple 日历 | ✅ | ❌ 降级为 ICS | ❌ 降级为 ICS |
+
+## 配置说明
+
+配置文件存储在 `~/.config/ccal/config.toml`。API key 存储在系统原生密钥链中（macOS Keychain / Linux Secret Service / Windows Credential Locker）。
+
+使用 Google 日历功能时，`ccal` 会用到两类本地文件：
+
+- `google_credentials.json`：从 Google Cloud Console 下载的 OAuth 客户端凭据 JSON，里面包含 client id 和 client secret。这个文件建议一直保留。
+- `google_token_*.json`：首次授权后生成的登录 token 缓存。里面的 access token 会过期，但通常可以自动刷新，所以平时不用手动处理。ccal 会根据当前凭据路径和 auth mode 选择对应的缓存文件。
+
+在 `ccal setup` 里，你可以把凭据 JSON 放到配置的目录中，也可以直接把 JSON 文件路径输入给 setup。教程里还会说明：
+
+- `Desktop app` 和 `TVs and Limited Input devices` 怎么选
+- `External` 和 `Internal` 的区别
+- `Testing` 状态和 `Test users`
+- 怎么找到 Google Calendar ID
+- setup 阶段会验证所选 Calendar ID 是否可访问
+
+你也可以在 `ccal setup` 的中间步骤里单独配置 Google 日历，即使默认输出方式不是 Google 也可以先把 API 配好。
+
+## 项目结构
+
+```
+src/
+├── main.py                  # CLI 入口 (Typer)
+├── config.py                # 配置与密钥链管理
+├── models/
+│   ├── model.py             # CalendarEvent Pydantic 模型
+│   └── llm.py               # 通过 litellm 调用 LLM 解析
+├── input/
+│   ├── ocr.py               # 图片文字提取 (pytesseract)
+│   └── geo.py               # 基于 IP 的地理定位与时区检测
+└── connections/
+    ├── google_calendar.py   # Google Calendar API 集成
+    ├── apple_calendar.py    # Apple Calendar AppleScript 集成 (macOS)
+    └── ics.py               # ICS 文件导出
+```
+
+## 许可证
+
+MIT

ccal-0.1.4/README.md

@@ -0,0 +1,159 @@
+# ccal
+
+[中文文档](README-zh_cn.md)
+
+A CLI tool that turns natural language text or images into calendar events. Powered by LLMs.
+
+## Features
+
+- **Text input** — describe an event in plain language, ccal parses it into structured fields
+- **Image input** — extract text from screenshots/photos via OCR, then parse
+- **Multi-LLM support** — works with OpenAI, Anthropic, Gemini, OpenRouter, Deepseek, Groq, Mistral, and more (via [litellm](https://github.com/BerriAI/litellm))
+- **ICS export** — generate standard `.ics` files importable by any calendar app
+- **Google Calendar sync** — create events directly on Google Calendar via API
+- **Apple Calendar sync** — add events via AppleScript (macOS only, auto-fallback to ICS on other platforms)
+- **Secure key storage** — API keys stored in your system keyring, never in plain text
+- **Geolocation** — auto-detect timezone and location for accurate event scheduling
+- **Stdin support** — pipe text from other commands
+
+## Requirements
+
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+- [Tesseract OCR](https://github.com/tesseract-ocr/tesseract) (for image input)
+
+## Installation
+
+```bash
+git clone https://github.com/your-username/ccal.git
+cd ccal
+uv sync
+```
+
+## Quick Start
+
+### 1. Setup
+
+```bash
+ccal setup
+```
+
+This will walk you through configuring:
+- LLM provider and model
+- API key (stored securely in system keyring)
+- Default output method (ICS file, Google Calendar, or Apple Calendar)
+- Google Calendar setup, including client type, auth mode, credentials location, and Calendar ID
+
+### 2. Add an event
+
+From text:
+
+```bash
+ccal add "Team meeting tomorrow at 3pm in Conference Room A"
+```
+
+From an image:
+
+```bash
+ccal add flyer.png
+```
+
+From stdin:
+
+```bash
+echo "Lunch with Alice Friday noon" | ccal add
+```
+
+With options:
+
+```bash
+ccal add "Dinner Friday 7pm at Luigi's" -o google       # sync to Google Calendar
+ccal add "Weekly standup Mon 9am" -o apple               # add to Apple Calendar (macOS)
+ccal add "Weekly standup Mon 9am" -o ics                  # export as .ics file
+ccal add "会议明天下午两点" -m anthropic/claude-sonnet-4-20250514  # use a specific model
+ccal add screenshot.png -l chi_sim                        # OCR with Chinese language
+ccal add "Demo at 2pm" -y                                 # skip confirmation
+ccal add "Demo at 2pm" --json                             # output as JSON
+```
+
+### 3. Parse only (no save)
+
+```bash
+ccal parse "Workshop next Wednesday 10am-12pm, Room 301"
+ccal parse "下周一上午10点团队周会" --json
+```
+
+### 4. View config
+
+```bash
+ccal config
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `ccal add [text\|image]` | Parse input and create a calendar event |
+| `ccal parse [text\|image]` | Parse and display event fields without saving |
+| `ccal setup` | Interactive configuration wizard |
+| `ccal config` | Show current configuration and platform info |
+
+### `ccal add` options
+
+| Option | Description |
+|--------|-------------|
+| `-o`, `--output` | Output method: `ics`, `google`, or `apple` |
+| `-p`, `--provider` | LLM provider name |
+| `-m`, `--model` | LLM model (e.g. `openai/gpt-4o`) |
+| `-y`, `--yes` | Skip confirmation, output directly |
+| `-l`, `--language` | OCR language (e.g. `chi_sim`, `eng+chi_sim`) |
+| `--json` | Output parsed event as JSON |
+
+## Platform Support
+
+| Feature | macOS | Linux | Windows |
+|---------|-------|-------|---------|
+| ICS export | ✅ | ✅ | ✅ |
+| Google Calendar | ✅ | ✅ | ✅ |
+| Apple Calendar | ✅ | ❌ fallback to ICS | ❌ fallback to ICS |
+
+## Configuration
+
+Config is stored at `~/.config/ccal/config.toml`. API keys are stored in your system's native keyring (macOS Keychain / Linux Secret Service / Windows Credential Locker).
+
+For Google Calendar integration, ccal uses two different local files:
+
+- `google_credentials.json`: the OAuth client credentials JSON downloaded from Google Cloud Console. This contains the client id and client secret. Keep this file around after setup.
+- `google_token_*.json`: the cached login token created after the first successful authorization. The access token inside can expire and refresh automatically, so you usually do not need to touch it. ccal picks the cache file based on the current credentials path and auth mode.
+
+During `ccal setup`, place the credentials JSON in the configured directory, or point setup directly at the JSON file. The setup tutorial also explains:
+
+- `Desktop app` vs `TVs and Limited Input devices`
+- `External` vs `Internal`
+- `Testing` status and `Test users`
+- how to find a Google Calendar ID
+- setup-time validation of the selected Calendar ID
+
+You can also configure Google Calendar during `ccal setup` through the dedicated middle step, even if your default output is not Google.
+
+## Project Structure
+
+```
+src/
+├── main.py                  # CLI entry point (Typer)
+├── config.py                # Configuration & keyring management
+├── models/
+│   ├── model.py             # CalendarEvent Pydantic model
+│   └── llm.py               # LLM parsing via litellm
+├── input/
+│   ├── ocr.py               # Image text extraction (pytesseract)
+│   └── geo.py               # IP-based geolocation for timezone
+└── connections/
+    ├── google_calendar.py   # Google Calendar API integration
+    ├── apple_calendar.py    # Apple Calendar via AppleScript (macOS)
+    └── ics.py               # ICS file export
+```
+
+## License
+
+MIT