timellama 0.1.0__tar.gz

timellama-0.1.0/.env.example

@@ -0,0 +1,12 @@
+# Required: Productive.io API credentials
+PRODUCTIVE_API_TOKEN=your_api_token
+PRODUCTIVE_ORG_ID=your_org_id
+PRODUCTIVE_USER_ID=your_user_id
+PRODUCTIVE_BILLING_CUTOFF_DAY=10  # Optional, defaults to 10
+
+# Optional: Calendar ICS URL (for calendar sync feature)
+ICS_CALENDAR_URL=https://outlook.office365.com/owa/calendar/.../calendar.ics
+
+# Optional: Ollama settings
+OLLAMA_MODEL=llama3.2:3b  # Default model
+OLLAMA_HOST=http://localhost:11434  # Default host

timellama-0.1.0/.gitignore

@@ -0,0 +1,70 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# macOS
+.DS_Store
+
+# Project specific
+*.ics
+.env.local

timellama-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Chrabaszcz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

timellama-0.1.0/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: timellama
+Version: 0.1.0
+Summary: CLI for Productive.io time tracking with calendar sync, team hours review, and local LLM support
+Project-URL: Homepage, https://github.com/achrabaszcz/timellama
+Project-URL: Repository, https://github.com/achrabaszcz/timellama
+Project-URL: Issues, https://github.com/achrabaszcz/timellama/issues
+Author: Adam Chrabaszcz
+License-Expression: MIT
+License-File: LICENSE
+Keywords: calendar,cli,hours,invoicing,mcp,ollama,productive,time-tracking
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Scheduling
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0.0
+Requires-Dist: ics-calendar-mcp>=0.1.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: ollama>=0.4.0
+Requires-Dist: productive-time-mcp>=0.1.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 🦙 TimeLlama
+
+CLI for Productive.io time tracking with calendar sync, team hours review, and local LLM support.
+
+TimeLlama helps you manage time tracking in Productive.io—sync calendar events to time entries, review team hours for invoicing, and get AI-powered work summaries. Uses a local LLM (Ollama) so all your data stays on your machine.
+
+## Features
+
+- **Calendar Sync**: Automatically create/update Productive time entries from your calendar
+- **Team Hours Review**: Check employee hours for billing periods with AI-generated summaries
+- **Invoice Approval**: Interactive workflow to review and approve team hours
+- **Interactive Chat**: REPL mode for managing time entries with LLM suggestions
+- **Cron-Ready**: One-shot sync command for automation
+- **Local LLM**: Uses Ollama for formatting—all data stays on your machine
+
+## Installation
+
+### Prerequisites
+
+1. **Ollama** (for LLM features):
+   ```bash
+   # macOS
+   brew install ollama
+
+   # Start Ollama server
+   ollama serve
+
+   # Pull the model
+   ollama pull llama3.2:3b
+   ```
+
+2. **Productive.io API access** with your API token
+
+3. **Calendar ICS file** (exported from Google Calendar, Outlook, etc.)
+
+### Install TimeLlama
+
+```bash
+# Via pipx (recommended - isolated environment)
+pipx install timellama
+
+# Or via pip
+pip install timellama
+
+# Or install from source
+git clone https://github.com/achrabaszcz/timellama.git
+cd timellama
+pip install -e .
+```
+
+## Configuration
+
+Create a `.env` file or set environment variables:
+
+```bash
+# Required: Productive.io API credentials
+PRODUCTIVE_API_TOKEN=your_api_token
+PRODUCTIVE_ORG_ID=your_org_id
+PRODUCTIVE_USER_ID=your_user_id
+
+# Optional: Calendar ICS URL (for calendar sync)
+ICS_CALENDAR_URL=https://outlook.office365.com/owa/calendar/.../calendar.ics
+
+# Optional: Billing period cutoff day (default: 10)
+PRODUCTIVE_BILLING_CUTOFF_DAY=10
+
+# Optional: Ollama settings
+OLLAMA_MODEL=llama3.2:3b
+OLLAMA_HOST=http://localhost:11434
+```
+
+### Getting Your Productive Credentials
+
+1. **API Token**: Go to Productive → Settings → API tokens
+2. **Organization ID**: Found in your Productive URL: `app.productive.io/org-ID/...`
+3. **User ID**: Use the Productive API or check your profile settings
+
+### Setting Up Your Calendar
+
+TimeLlama fetches calendar data from an ICS URL. Most calendar providers offer a shareable ICS link:
+
+**Outlook/Office 365**:
+1. Go to Outlook Calendar → Settings → Shared calendars
+2. Publish your calendar and copy the ICS link
+3. Set `ICS_CALENDAR_URL` to the link
+
+**Google Calendar**:
+1. Go to Google Calendar → Settings → Settings for my calendars
+2. Select your calendar → Integrate calendar
+3. Copy the "Secret address in iCal format"
+4. Set `ICS_CALENDAR_URL` to the link
+
+## Usage
+
+### Check Configuration
+
+```bash
+timellama doctor
+```
+
+### Show Today's Status
+
+```bash
+timellama status
+```
+
+### Sync Calendar to Productive
+
+```bash
+# Sync today's calendar events
+timellama sync
+
+# Dry run - see what would happen
+timellama sync --dry-run
+
+# Include LLM suggestions for additional items
+timellama sync --suggestions
+```
+
+### Interactive Chat Mode
+
+```bash
+timellama chat
+```
+
+Commands in chat mode:
+- `sync` - Sync calendar to Productive
+- `show` - Show current status
+- `add <item>` - Add item to today's log
+- `help` - Show help
+- `quit` - Exit
+
+### Add Item to Today's Log
+
+```bash
+timellama add Code review for PR 123
+timellama add Debugging authentication issue
+```
+
+### Employee Hours
+
+```bash
+# Get employee hours for billing period
+timellama hours "John Doe"
+
+# Current calendar month
+timellama hours "John" --period current
+
+# Previous month
+timellama hours "Jane" --period previous
+
+# Custom date range
+timellama hours "John" --after 2026-01-01 --before 2026-01-31
+
+# With AI summary
+timellama hours "John" --summary
+```
+
+### Interactive Approval Workflow
+
+```bash
+timellama approve
+```
+
+## Cron Setup
+
+For automated daily sync:
+
+```bash
+# Edit crontab
+crontab -e
+
+# Add line (sync at 6 PM every weekday)
+0 18 * * 1-5 /path/to/timellama sync >> /var/log/timellama.log 2>&1
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        timellama CLI                        │
+├─────────────────────────────────────────────────────────────┤
+│  Commands:                                                  │
+│  - timellama chat           (interactive mode)              │
+│  - timellama sync           (automated sync for cron)       │
+│  - timellama status         (show today's log)              │
+│  - timellama hours <name>   (employee work summary)         │
+│  - timellama approve        (review team hours)             │
+└─────────────────────────────────────────────────────────────┘
+         │                    │                    │
+         ▼                    ▼                    ▼
+┌─────────────┐      ┌─────────────┐      ┌─────────────┐
+│   Ollama    │      │ ics-calendar│      │ productive- │
+│  (local)    │      │    MCP      │      │  time MCP   │
+│ llama3.2:3b │      │ (bundled)   │      │  (bundled)  │
+└─────────────┘      └─────────────┘      └─────────────┘
+```
+
+**Bundled MCP Servers**: The `productive-time-mcp` and `ics-calendar-mcp` servers are installed as dependencies. TimeLlama spawns them automatically—no separate setup needed.
+
+## Privacy
+
+- All data stays local
+- Ollama runs on localhost:11434
+- MCP servers run locally (stdio)
+- Only Productive API calls go external (required for time tracking)
+- No calendar data sent to cloud LLMs
+
+## Development
+
+```bash
+# Clone repo
+git clone https://github.com/achrabaszcz/timellama.git
+cd timellama
+
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Lint
+ruff check src/
+```
+
+## License
+
+MIT

timellama-0.1.0/README.md

@@ -0,0 +1,228 @@
+# 🦙 TimeLlama
+
+CLI for Productive.io time tracking with calendar sync, team hours review, and local LLM support.
+
+TimeLlama helps you manage time tracking in Productive.io—sync calendar events to time entries, review team hours for invoicing, and get AI-powered work summaries. Uses a local LLM (Ollama) so all your data stays on your machine.
+
+## Features
+
+- **Calendar Sync**: Automatically create/update Productive time entries from your calendar
+- **Team Hours Review**: Check employee hours for billing periods with AI-generated summaries
+- **Invoice Approval**: Interactive workflow to review and approve team hours
+- **Interactive Chat**: REPL mode for managing time entries with LLM suggestions
+- **Cron-Ready**: One-shot sync command for automation
+- **Local LLM**: Uses Ollama for formatting—all data stays on your machine
+
+## Installation
+
+### Prerequisites
+
+1. **Ollama** (for LLM features):
+   ```bash
+   # macOS
+   brew install ollama
+
+   # Start Ollama server
+   ollama serve
+
+   # Pull the model
+   ollama pull llama3.2:3b
+   ```
+
+2. **Productive.io API access** with your API token
+
+3. **Calendar ICS file** (exported from Google Calendar, Outlook, etc.)
+
+### Install TimeLlama
+
+```bash
+# Via pipx (recommended - isolated environment)
+pipx install timellama
+
+# Or via pip
+pip install timellama
+
+# Or install from source
+git clone https://github.com/achrabaszcz/timellama.git
+cd timellama
+pip install -e .
+```
+
+## Configuration
+
+Create a `.env` file or set environment variables:
+
+```bash
+# Required: Productive.io API credentials
+PRODUCTIVE_API_TOKEN=your_api_token
+PRODUCTIVE_ORG_ID=your_org_id
+PRODUCTIVE_USER_ID=your_user_id
+
+# Optional: Calendar ICS URL (for calendar sync)
+ICS_CALENDAR_URL=https://outlook.office365.com/owa/calendar/.../calendar.ics
+
+# Optional: Billing period cutoff day (default: 10)
+PRODUCTIVE_BILLING_CUTOFF_DAY=10
+
+# Optional: Ollama settings
+OLLAMA_MODEL=llama3.2:3b
+OLLAMA_HOST=http://localhost:11434
+```
+
+### Getting Your Productive Credentials
+
+1. **API Token**: Go to Productive → Settings → API tokens
+2. **Organization ID**: Found in your Productive URL: `app.productive.io/org-ID/...`
+3. **User ID**: Use the Productive API or check your profile settings
+
+### Setting Up Your Calendar
+
+TimeLlama fetches calendar data from an ICS URL. Most calendar providers offer a shareable ICS link:
+
+**Outlook/Office 365**:
+1. Go to Outlook Calendar → Settings → Shared calendars
+2. Publish your calendar and copy the ICS link
+3. Set `ICS_CALENDAR_URL` to the link
+
+**Google Calendar**:
+1. Go to Google Calendar → Settings → Settings for my calendars
+2. Select your calendar → Integrate calendar
+3. Copy the "Secret address in iCal format"
+4. Set `ICS_CALENDAR_URL` to the link
+
+## Usage
+
+### Check Configuration
+
+```bash
+timellama doctor
+```
+
+### Show Today's Status
+
+```bash
+timellama status
+```
+
+### Sync Calendar to Productive
+
+```bash
+# Sync today's calendar events
+timellama sync
+
+# Dry run - see what would happen
+timellama sync --dry-run
+
+# Include LLM suggestions for additional items
+timellama sync --suggestions
+```
+
+### Interactive Chat Mode
+
+```bash
+timellama chat
+```
+
+Commands in chat mode:
+- `sync` - Sync calendar to Productive
+- `show` - Show current status
+- `add <item>` - Add item to today's log
+- `help` - Show help
+- `quit` - Exit
+
+### Add Item to Today's Log
+
+```bash
+timellama add Code review for PR 123
+timellama add Debugging authentication issue
+```
+
+### Employee Hours
+
+```bash
+# Get employee hours for billing period
+timellama hours "John Doe"
+
+# Current calendar month
+timellama hours "John" --period current
+
+# Previous month
+timellama hours "Jane" --period previous
+
+# Custom date range
+timellama hours "John" --after 2026-01-01 --before 2026-01-31
+
+# With AI summary
+timellama hours "John" --summary
+```
+
+### Interactive Approval Workflow
+
+```bash
+timellama approve
+```
+
+## Cron Setup
+
+For automated daily sync:
+
+```bash
+# Edit crontab
+crontab -e
+
+# Add line (sync at 6 PM every weekday)
+0 18 * * 1-5 /path/to/timellama sync >> /var/log/timellama.log 2>&1
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        timellama CLI                        │
+├─────────────────────────────────────────────────────────────┤
+│  Commands:                                                  │
+│  - timellama chat           (interactive mode)              │
+│  - timellama sync           (automated sync for cron)       │
+│  - timellama status         (show today's log)              │
+│  - timellama hours <name>   (employee work summary)         │
+│  - timellama approve        (review team hours)             │
+└─────────────────────────────────────────────────────────────┘
+         │                    │                    │
+         ▼                    ▼                    ▼
+┌─────────────┐      ┌─────────────┐      ┌─────────────┐
+│   Ollama    │      │ ics-calendar│      │ productive- │
+│  (local)    │      │    MCP      │      │  time MCP   │
+│ llama3.2:3b │      │ (bundled)   │      │  (bundled)  │
+└─────────────┘      └─────────────┘      └─────────────┘
+```
+
+**Bundled MCP Servers**: The `productive-time-mcp` and `ics-calendar-mcp` servers are installed as dependencies. TimeLlama spawns them automatically—no separate setup needed.
+
+## Privacy
+
+- All data stays local
+- Ollama runs on localhost:11434
+- MCP servers run locally (stdio)
+- Only Productive API calls go external (required for time tracking)
+- No calendar data sent to cloud LLMs
+
+## Development
+
+```bash
+# Clone repo
+git clone https://github.com/achrabaszcz/timellama.git
+cd timellama
+
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Lint
+ruff check src/
+```
+
+## License
+
+MIT

timellama-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "timellama"
+version = "0.1.0"
+description = "CLI for Productive.io time tracking with calendar sync, team hours review, and local LLM support"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Adam Chrabaszcz" }
+]
+keywords = ["productive", "time-tracking", "calendar", "ollama", "mcp", "cli", "invoicing", "hours"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Scheduling",
+]
+
+dependencies = [
+    "mcp>=1.0.0",
+    "productive-time-mcp>=0.1.0",
+    "ics-calendar-mcp>=0.1.0",
+    "ollama>=0.4.0",
+    "click>=8.0.0",
+    "rich>=13.0.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "ruff>=0.1.0",
+]
+
+[project.scripts]
+timellama = "timellama.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/achrabaszcz/timellama"
+Repository = "https://github.com/achrabaszcz/timellama"
+Issues = "https://github.com/achrabaszcz/timellama/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/timellama"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

timellama-0.1.0/src/timellama/__init__.py

@@ -0,0 +1,3 @@
+"""TimeLlama - Calendar to Productive.io time tracking automation."""
+
+__version__ = "0.1.0"

timellama-0.1.0/src/timellama/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for running timellama as a module."""
+
+from timellama.cli import main
+
+if __name__ == "__main__":
+    main()