Carranza Family Manager

Intelligent orchestration system for family operations, starting with automated financial monitoring.

Overview

The Carranza Family Manager is a modular agent system designed to automate and optimize family operations. Each sub-agent handles a specific domain (finance, calendar, meal planning, etc.), orchestrated by a master agent that coordinates between them.

Current Agents

• Finance Agent ✅ - Automated financial monitoring, burn rate tracking, and Telegram reporting

Planned Agents

• Calendar Agent 🔜 - Family schedule coordination, conflict detection, reminder management
• Meal Planning Agent 🔜 - Weekly meal plans, grocery lists, recipe suggestions
• Household Agent 🔜 - Maintenance tracking, chore assignments, inventory management
• Travel Agent 🔜 - Trip planning, itinerary management, packing lists

---

Architecture

CarranzaFamilyManager/
├── agents/              # Sub-agents for specific domains
│   └── finance/         # Finance Agent (active)
├── orchestrator/        # Master orchestrator (future)
├── shared/              # Shared utilities across all agents
│   ├── config.py
│   ├── sheets_handler.py
│   └── telegram_bot.py
├── docs/                # Documentation
├── data/                # Historical data
└── .github/workflows/   # Automation (GitHub Actions)

---

Finance Agent (Active)

Automated family finance monitoring that:

• Syncs transactions from Tiller Money daily
• Classifies transactions with AI-powered categorization
• Tracks "Daily Burn Rate" against budget targets
• Sends automated status reports to Telegram (Mon/Thu 5 PM PT)
• Flags at-risk spending categories

Key Features:

• ✅ Cloud-based automation (GitHub Actions)
• ✅ Simple "Ignore" column for excluding reimbursables
• ✅ Substring pattern matching for merchant categorization
• ✅ Correction layer for edge case classifications
• ✅ Human-in-the-loop for ambiguous transactions

Quick Start:

# Manual report
python agents/finance/run_agent.py report

# Sync latest from Tiller
python agents/finance/sync_from_tiller.py

# Full workflow (sync + report)
python agents/finance/run_automated_report.py

📖 Full Documentation: docs/AUTOMATION_SETUP.md

---

Setup

Prerequisites

• Python 3.11+
• Tiller Money subscription ($79/year)
• Google Sheets API access (service account)
• Telegram Bot

Installation

1. Clone the repository:

   git clone https://github.com/YOUR_USERNAME/CarranzaFamilyManager.git
   cd CarranzaFamilyManager

2. Install dependencies:

   pip install -r requirements.txt

3. Configure credentials:

   • Copy .env.example to .env
   • Add your Telegram bot token and chat ID
   • Place google-credentials.json in root directory

4. Set up Google Sheets:

   python agents/finance/setup_sheets.py

5. Test the system:

   python agents/finance/test_bot.py

6. Enable cloud automation:

   • Follow docs/GITHUB_SETUP_INSTRUCTIONS.md

---

Tech Stack

• Orchestrator: Claude 3.5 Sonnet (via Claude Code)
• Banking Data: Tiller Money → Google Sheets
• Database: Google Sheets
• Communication: Telegram Bot API
• Automation: GitHub Actions (cloud-based)
• Languages: Python 3.11+

---

Daily Operations

Exclude Transactions (Reimbursables, etc.)

1. Open "Carranza Family Finance Agent" Google Sheet
2. Go to Raw_Transactions tab
3. Find transaction, mark Ignore column as "Yes"
4. Run report to see updated burn rate

Trigger Manual Report

python agents/finance/run_agent.py report

Add New Merchants

1. Open Learned_Mappings tab in Google Sheets
2. Add row: [merchant pattern, category, notes]
3. Run: python agents/finance/reclassify_all.py

---

Project Roadmap

Phase 1: Finance Agent (Complete)

• Tiller Money integration
• Transaction classification with AI
• Burn rate calculation & projections
• Telegram reporting automation
• GitHub Actions deployment

Phase 2: Master Orchestrator (In Progress)

• Design orchestrator architecture
• Inter-agent communication protocol
• Unified dashboard/interface
• Context sharing between agents

Phase 3: Additional Agents

• Calendar Agent (family scheduling)
• Meal Planning Agent (groceries & recipes)
• Household Agent (maintenance & chores)
• Travel Agent (trip planning)

---

Documentation

Document	Description
AUTOMATION_SETUP.md	GitHub Actions cloud automation setup
QUICK_REFERENCE.md	Daily operations & commands
GITHUB_SETUP_INSTRUCTIONS.md	Step-by-step GitHub repo setup
REIMBURSABLE_GUIDE.md	How to exclude transactions

---

Contributing

This is a personal family project, but feel free to fork and adapt for your own use!

---

License

Private family project - All rights reserved.

---

Contact

• Telegram: Primary communication channel
• GitHub Issues: For bugs or feature requests

---

Built with ❤️ for the Carranza Family