Bookkeeper (Agent Zero)

{
  "name": "bookkeeper",
  "version": "1.0.0",
  "description": "Financial record-keeping and transaction categorization specialist",
  "author": "RunClaw",
  "agent_zero_version": ">=0.9.8",
  "hooks": [
    "agent_init"
  ],
  "tools": [
    "transaction_categorizer",
    "receipt_parser"
  ],
  "dependencies": []
}

# Bookkeeper Plugin

You have the Bookkeeper plugin active. You are a specialist in financial record-keeping, transaction categorization, and accounting fundamentals.

## Core Principles

1. **Accuracy First** -- Financial data must be precise. Never round unless explicitly asked.
2. **Double-Entry** -- Every transaction has two sides. Debits equal credits.
3. **Consistent Categorization** -- Same vendor/type always maps to the same category.
4. **Audit Trail** -- Always explain categorization decisions, especially unusual ones.

## Standard Chart of Accounts

### Income
- Revenue (product sales, service fees)
- Interest Income
- Other Income (refunds, credits)

### Expenses
- Technology Expenses (SaaS, hosting, domains)
- Contractor Payments
- Payroll & Benefits
- Office & Equipment
- Meals & Entertainment
- Travel
- Marketing & Advertising
- Professional Services (legal, accounting)
- Insurance
- Operating Expenses (misc)

### Assets
- Cash & Bank Accounts
- Accounts Receivable
- Prepaid Expenses

### Liabilities
- Accounts Payable
- Credit Card Balances
- Deferred Revenue

## Output Standards

- Always use consistent currency formatting ($1,234.56)
- Include category and account for every transaction
- Flag ambiguous transactions for human review
- Show totals and percentages for summaries

# Bookkeeper -- Behavioral Instructions

## Transaction Categorization Workflow

1. **Read the transaction** -- Extract vendor name, amount, date, description
2. **Match to category** -- Use the chart of accounts. Match by vendor name first, then description keywords
3. **Flag unknowns** -- If a transaction doesn't clearly fit, mark it as "NEEDS REVIEW" with your best guess
4. **Calculate totals** -- Always provide category subtotals and overall summary

## Common Vendor Mappings

| Vendor Pattern | Category | Notes |
|---------------|----------|-------|
| AWS, GCP, Azure, DigitalOcean | Cloud Infrastructure | Technology Expenses |
| GitHub, GitLab, Bitbucket | Developer Tools | Technology Expenses |
| Figma, Canva, Adobe | Design Software | Technology Expenses |
| Slack, Notion, Linear | Productivity SaaS | Technology Expenses |
| Stripe, PayPal (fees) | Payment Processing | Operating Expenses |
| Stripe, PayPal (payouts) | Revenue | Income |
| Uber, Lyft | Travel/Transport | Travel or Meals (context-dependent) |

## Financial Report Formats

### Monthly P&L
- Revenue section (all income sources)
- Expenses section (grouped by category, sorted by amount descending)
- Bottom line (gross profit, net profit, net margin %)
- Comparison to previous month if data available

### Transaction Log
- Table format: Date | Description | Amount | Category | Account
- Sorted by date ascending
- Running balance if single account

### Cash Flow Summary
- Opening balance
- Inflows (grouped)
- Outflows (grouped)
- Closing balance
- Net change

## Red Flags to Watch For

- Duplicate transactions (same amount, same vendor, same day)
- Unusually large transactions (>3x average for that category)
- Missing regular subscriptions (expected monthly charge absent)
- Negative balances where they shouldn't exist
- Foreign currency transactions that may need conversion

"""
Tool: TransactionCategorizer
Description: Categorize financial transactions against a chart of accounts
Plugin: bookkeeper

Takes raw transaction data (description, amount) and maps it to the
appropriate accounting category using vendor matching and keyword analysis.
"""

from python.helpers.tool import Tool, Response


class TransactionCategorizer(Tool):
    """Categorize a financial transaction.

    Use this tool to classify transactions by vendor name and description
    against the standard chart of accounts.
    """

    VENDOR_CATEGORIES = {
        "aws": ("Cloud Infrastructure", "Technology Expenses"),
        "gcp": ("Cloud Infrastructure", "Technology Expenses"),
        "azure": ("Cloud Infrastructure", "Technology Expenses"),
        "digitalocean": ("Cloud Infrastructure", "Technology Expenses"),
        "hetzner": ("Cloud Infrastructure", "Technology Expenses"),
        "github": ("Developer Tools", "Technology Expenses"),
        "figma": ("Design Software", "Technology Expenses"),
        "adobe": ("Design Software", "Technology Expenses"),
        "canva": ("Design Software", "Technology Expenses"),
        "slack": ("Productivity SaaS", "Technology Expenses"),
        "notion": ("Productivity SaaS", "Technology Expenses"),
        "linear": ("Productivity SaaS", "Technology Expenses"),
        "spotify": ("Software Subscriptions", "Technology Expenses"),
        "stripe": ("Payment Processing", "Operating Expenses"),
        "paypal": ("Payment Processing", "Operating Expenses"),
    }

    async def execute(
        self,
        description: str = "",
        amount: str = "",
        is_income: bool = False,
        **kwargs,
    ):
        """Categorize a transaction.

        Args:
            description: Transaction description or vendor name
            amount: Transaction amount as string (e.g., "$49.99")
            is_income: Whether this is an income transaction (default: False)
        """
        if not description:
            return Response(
                message="Please provide a transaction description.",
                break_loop=False,
            )

        desc_lower = description.lower()
        category = None
        account = None

        # Try vendor matching
        for vendor, (cat, acct) in self.VENDOR_CATEGORIES.items():
            if vendor in desc_lower:
                category = cat
                account = acct
                break

        if is_income:
            category = "Revenue"
            account = "Income"

        if category:
            return Response(
                message=(
                    f"**Categorized:** {description}\n"
                    f"- Amount: {amount}\n"
                    f"- Category: {category}\n"
                    f"- Account: {account}"
                ),
                break_loop=False,
            )

        return Response(
            message=(
                f"**NEEDS REVIEW:** {description}\n"
                f"- Amount: {amount}\n"
                f"- Category: Unknown (no vendor match)\n"
                f"- Suggestion: Review and manually categorize"
            ),
            break_loop=False,
        )

"""
Tool: ReceiptParser
Description: Extract structured data from receipt text or descriptions
Plugin: bookkeeper

Parses receipt information to extract vendor, amount, date, line items,
tax, and total for structured bookkeeping entry.
"""

from python.helpers.tool import Tool, Response


class ReceiptParser(Tool):
    """Parse receipt text into structured transaction data.

    Use this tool when you have raw receipt text and need to extract
    vendor, amount, date, line items, and tax information.
    """

    async def execute(self, receipt_text: str = "", **kwargs):
        """Parse receipt text into structured data.

        Args:
            receipt_text: Raw receipt text or description to parse
        """
        if not receipt_text:
            return Response(
                message="Please provide receipt text to parse.",
                break_loop=False,
            )

        lines = receipt_text.strip().split("\n")
        line_count = len(lines)

        return Response(
            message=(
                f"## Receipt Analysis\n\n"
                f"- **Lines to parse:** {line_count}\n"
                f"- **Raw text length:** {len(receipt_text)} chars\n\n"
                f"Extracting structured data: vendor name, date, line items, "
                f"subtotal, tax, total, and payment method. "
                f"Results will be formatted for bookkeeping entry."
            ),
            break_loop=False,
        )

"""
Extension: agent_init
Plugin: bookkeeper

Runs when the agent initializes. Logs activation of the Bookkeeper plugin
and sets up runtime state including default chart of accounts.
"""

from python.helpers.log import Log


async def execute(agent, **kwargs):
    """Initialize the Bookkeeper plugin."""
    Log.info("Bookkeeper plugin activated", head="plugin")
    Log.info(
        "Transaction categorization and financial record-keeping enabled",
        head="plugin",
    )

    if not hasattr(agent, "plugin_state"):
        agent.plugin_state = {}
    agent.plugin_state["bookkeeper"] = {
        "active": True,
        "version": "1.0.0",
        "chart_of_accounts": [
            "Revenue",
            "Technology Expenses",
            "Contractor Payments",
            "Operating Expenses",
            "Travel",
            "Marketing",
        ],
    }