Metadata-Version: 2.4
Name: cosinabox
Version: 0.1.3
Summary: Open-source Chief of Staff in a box. Opinionated, proactive, runs on your own infra.
Project-URL: Homepage, https://github.com/rovikrobert/cosinabox
Project-URL: Source, https://github.com/rovikrobert/cosinabox
Project-URL: Issues, https://github.com/rovikrobert/cosinabox/issues
Project-URL: Changelog, https://github.com/rovikrobert/cosinabox/blob/main/CHANGELOG.md
Author: Cantina
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Keywords: agent,anthropic,chief-of-staff,claude,productivity,telegram
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Office/Business :: Scheduling
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.40
Requires-Dist: apscheduler>=3.10
Requires-Dist: click>=8.1
Requires-Dist: jinja2>=3.1
Requires-Dist: jsonschema>=4.21
Requires-Dist: python-dotenv>=1.0
Requires-Dist: python-telegram-bot>=21.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: attio
Requires-Dist: httpx>=0.27; extra == 'attio'
Provides-Extra: consult
Requires-Dist: mcp>=1.12; extra == 'consult'
Provides-Extra: dev
Requires-Dist: mcp>=1.12; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: types-jsonschema; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Provides-Extra: fireflies
Requires-Dist: httpx>=0.27; extra == 'fireflies'
Provides-Extra: google
Requires-Dist: google-api-python-client>=2.120; extra == 'google'
Requires-Dist: google-auth-httplib2>=0.2; extra == 'google'
Requires-Dist: google-auth-oauthlib>=1.2; extra == 'google'
Provides-Extra: search
Requires-Dist: httpx>=0.27; extra == 'search'
Description-Content-Type: text/markdown

# cosinabox

[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)

Open-source Chief of Staff in a box. Opinionated, proactive, runs on your own infra.

CoSinaBox is a self-hosted AI Chief of Staff agent that runs your day. It ships with default morning briefing, pre-meeting prep, evening wrap, weekly review, and follow-up tracking. You configure *who it's for*, not *what it does*.

## Key Features

- **5 built-in jobs:** morning briefing, pre-meeting prep, evening wrap, weekly review, follow-up nudges
- **Telegram-first:** primary interface via Telegram bot
- **Google integration:** Calendar, Gmail, Drive (optional)
- **SQLite memory:** persistent context without external databases
- **Zero telemetry:** runs entirely on your infra with your API keys
- **Extensible:** add custom jobs via a thin user repo

## Prerequisites

- Python 3.11+
- [Anthropic API key](https://console.anthropic.com/) (Claude powers the agent)
- Telegram bot token (via [@BotFather](https://t.me/botfather))
- Optional: Google OAuth credentials (for Calendar/Gmail/Drive)
- Optional: Fireflies API key (for meeting transcripts)

## Quickstart

```bash
# Install the engine
pip install cosinabox

# Scaffold your user repo
cosinabox init my-cos
cd my-cos

# Configure (edit .env with your API keys, then customize personality.md)
cp .env.example .env
$EDITOR .env
$EDITOR personality.md

# Verify setup
cosinabox doctor

# Run
cosinabox run
```

## Development Setup

```bash
# Clone and install in dev mode
git clone https://github.com/user/cosinabox.git
cd cosinabox
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,google,fireflies,search,attio]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest

# Lint & type-check
ruff check src tests
mypy src
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for full development guidelines.

## Project Structure

```
cosinabox/
├── src/cosinabox/
│   ├── agent/         # Claude API loop, routing, cost tracking
│   ├── app/           # App orchestrator (config, tools, jobs, alerts, chat)
│   ├── bot/           # Telegram adapter
│   ├── cli/           # CLI commands (init, run, doctor)
│   ├── jobs/          # 5 built-in jobs
│   ├── memory/        # SQLite persistence layer
│   ├── scheduling/    # APScheduler integration
│   ├── tools/         # External integrations (Google, Fireflies, Serper)
│   ├── prompts/       # Default prompt templates
│   ├── personas/      # Persona templates
│   ├── schemas/       # JSON schemas for config validation
│   └── templates/     # User-repo scaffold (used by `cosinabox init`)
├── tests/
│   ├── unit/          # Unit tests
│   └── stress/        # Stress/integration tests
└── docs/              # Architecture and design docs
```

## Architecture

CoSinaBox follows an **engine + thin user repo** pattern (similar to Hugo + content, or Next.js + app code):

- **Engine** (`cosinabox` package): the agent loop, scheduling, tools, and built-in jobs
- **User repo** (scaffolded by `cosinabox init`): your personality, stakeholders, integrations config, and optional custom jobs

For detailed architecture, see [docs/specs/2026-04-11-cosinabox-design.md](docs/specs/2026-04-11-cosinabox-design.md).

## Privacy

- Zero telemetry by default -- no data leaves your machine except to APIs you explicitly configure
- AGPL-3.0 license to protect against SaaS extraction without contribution
- README documents every external service the engine touches

## Running Tests

```bash
# All tests
pytest

# Unit tests only
pytest tests/unit/

# With coverage
pytest --cov=cosinabox
```

## License

AGPL-3.0-or-later. See [LICENSE](LICENSE).
