Frequently Asked Questions¶

Common questions about Poolula Platform installation, usage, and troubleshooting.

General Questions¶

What is Poolula Platform?¶

Poolula Platform is an integrated data hub and natural language query system for Poolula LLC, a Colorado-based rental property business. It combines transaction analysis, document search, and compliance tracking with an AI-powered chatbot interface.

Who should use this?¶

Poolula Platform is designed for:

LLC Owners - Track compliance obligations and deadlines
Bookkeepers - Manage transactions and prepare tax filings
Property Managers - Monitor leases, insurance, and maintenance
Compliance Officers - Ensure regulatory requirements are met

Is this a replacement for QuickBooks?¶

No. Poolula Platform is a question-answering system, not accounting software. It helps you:

Query your financial data using natural language
Search business documents for specific information
Track compliance deadlines
Verify data through evaluation harness

For accounting, use QuickBooks, Wave, or similar software. Poolula Platform complements accounting software by providing natural language access to your data.

Is my data secure?¶

Yes, with caveats:

All data stored locally in SQLite (no cloud storage)
Documents never leave your machine
Only API calls to Claude AI (for query processing)
No sensitive data sent to Claude (only queries and responses)

For production deployment, implement proper authentication and encryption.

Installation & Setup¶

What are the minimum system requirements?¶

Required:

Python 3.13+
4GB RAM
2GB free disk space
Internet connection (for AI API calls)

Recommended:

8GB+ RAM
10GB+ free disk space
SSD for better database performance

Do I need a Claude API key?¶

Yes, the chatbot requires an Anthropic Claude API key. Sign up at console.anthropic.com.

Pricing: Claude API uses pay-as-you-go pricing. Typical queries cost \(0.01-\)0.05 each with Sonnet 4.5.

Can I run this without the chatbot?¶

Yes. You can use:

Database directly (SQLite)
API endpoints (properties, transactions, documents)
Import/export scripts
CLI commands (non-chatbot features)

The chatbot is optional if you only need data management.

Why Python 3.13? Can I use Python 3.12?¶

Python 3.13+ is required for:

Latest type hint features
Performance improvements
Modern async support

Python 3.12 may work but is not officially supported.

Usage Questions¶

How do I import Airbnb transactions?¶

Export transactions from Airbnb (CSV format)
Get your property UUID from the database
Run the import script:

uv run python scripts/import_airbnb_transactions.py \
    --csv data/airbnb_export.csv \
    --property-id <uuid> \
    --dry-run  # Preview first

Review the preview
Run without --dry-run to actually import

See Importing Data Guide for details.

What accounting method does the system use?¶

Accrual accounting for Airbnb transactions:

Revenue recognized on checkout date (when service provided)
Expenses recognized on payout date (when fee charged)

This matches standard rental property accounting practices.

How do I add my own documents?¶

Place documents in documents/ directory (organized by type)
Update data/document_metadata.csv with metadata
Run ingestion script:

uv run python scripts/ingest_documents.py

Supported formats: PDF, DOCX, TXT, MD

How accurate is the chatbot?¶

The chatbot uses Claude Sonnet 4.5 with RAG (Retrieval-Augmented Generation). Accuracy depends on:

Data quality - Accurate database records
Document completeness - All relevant docs ingested
Query clarity - Well-formed questions

Target accuracy: ≥90% (measured via evaluation harness)

To verify accuracy, check:

Sources cited by the chatbot
Run evaluation: uv run python apps/evaluator/evaluation_harness.py

What transaction categories are supported?¶

30+ categories including:

Income: RENTAL_INCOME, OTHER_REVENUE
Utilities: UTILITIES_GAS, UTILITIES_ELECTRIC, UTILITIES_WATER
Maintenance: REPAIRS_MAINTENANCE, LANDSCAPING
Professional: PROPERTY_MANAGEMENT, LEGAL_PROFESSIONAL, ACCOUNTING
Insurance: INSURANCE_PROPERTY, INSURANCE_LIABILITY
Taxes: PROPERTY_TAXES, INCOME_TAXES
Capital: CAPITAL_IMPROVEMENT

See core/database/enums.py for complete list.

Troubleshooting¶

API server won't start¶

Error: Address already in use

Solution: Another process is using port 8082.

# Find process using port 8082
lsof -i :8082

# Kill the process (replace PID)
kill -9 <PID>

# Or use a different port
uv run uvicorn apps.api.main:app --port 8083

Database connection fails¶

Error: Could not connect to database

Solutions:

Check if database file exists:
```
ls -la poolula.db
```
Run migrations if missing:
```
.venv/bin/alembic upgrade head
```
Check DATABASE_URL in .env:
```
cat .env | grep DATABASE_URL
```

ChromaDB import errors¶

Error: ModuleNotFoundError: No module named 'chromadb'

Solution: Install RAG dependencies:

uv sync --group rag

Error: ChromaDB requires C++ compiler

Solution: Install build tools:

macOSLinux

xcode-select --install

sudo apt install build-essential

Chatbot returns "no data found" but data exists¶

Possible causes:

Wrong query format - Try rephrasing
Data not in expected format - Check transaction categories

Duplicate transactions - Run deduplication:

uv run python scripts/remove_duplicate_transactions.py --dry-run

Debug steps:

Query database directly:

sqlite3 poolula.db "SELECT * FROM transaction WHERE transaction_date >= '2025-08-01'"

Check AI tool usage (look at API logs)

Run evaluation to check accuracy:

uv run python apps/evaluator/evaluation_harness.py

Documents not found in search¶

Possible causes:

Documents not ingested - Run ingestion:

uv run python scripts/ingest_documents.py --list

Metadata missing - Check data/document_metadata.csv

ChromaDB not initialized - Reingest documents:

uv run python scripts/ingest_documents.py --force

Import script fails¶

Error: No such file or directory: data/airbnb_export.csv

Solution: Provide correct path to CSV file:

uv run python scripts/import_airbnb_transactions.py \
    --csv /full/path/to/airbnb_export.csv \
    --property-id <uuid>

Error: Invalid property ID

Solution: Get correct property UUID from database:

sqlite3 poolula.db "SELECT id, address FROM property"

Development Questions¶

How do I add a new transaction category?¶

Edit core/database/enums.py:

class TransactionCategory(str, Enum):
    # ... existing categories ...
    NEW_CATEGORY = "NEW_CATEGORY"

Create migration:

.venv/bin/alembic revision --autogenerate -m "Add NEW_CATEGORY"
.venv/bin/alembic upgrade head

Update tests and documentation

How do I add a new API endpoint?¶

Create route in apps/api/routes/:

@router.get("/new-endpoint")
def new_endpoint():
    return {"message": "Hello"}

Add router to apps/api/main.py:

from apps.api.routes import new_routes
app.include_router(new_routes.router, prefix="/api/v1")

Test endpoint:

curl http://localhost:8082/api/v1/new-endpoint

How do I run tests?¶

# All tests
uv run pytest

# Specific test file
uv run pytest tests/test_models.py

# With coverage
uv run pytest --cov=core --cov=apps --cov-report=html
open htmlcov/index.html

How do I contribute?¶

This is a solo-developer project for Poolula LLC. For development workflow:

Code style: Follow ruff linting (run uv run ruff check)
Testing: Maintain ≥80% coverage (see Testing Guide)
Documentation: Update relevant docs in docs/ directory
Standards: Type hints throughout, Pydantic validation

Advanced Questions¶

Can I deploy this to a server?¶

Yes. For production:

Replace SQLite with PostgreSQL
Add authentication (OAuth2 / JWT)
Enable HTTPS (reverse proxy with nginx)
Implement rate limiting
Add monitoring and logging

See deployment guides (coming soon).

Can I integrate with QuickBooks?¶

Not currently, but this is possible via:

QuickBooks API integration
CSV export/import
Custom sync scripts

This is on the roadmap for future development.

Can I add custom AI tools?¶

Yes! Add new tools to apps/chatbot/tool_manager.py:

def get_custom_tool_definition():
    return {
        "name": "custom_tool",
        "description": "...",
        "input_schema": {...}
    }

def execute_custom_tool(**kwargs):
    # Implementation
    return result

Register in tool_manager.py and the AI can use it.

Can I use a different AI model?¶

Currently supports Anthropic Claude only. To add other models:

Implement adapter in apps/chatbot/ai_generator.py
Update tool definitions for model-specific format
Test with evaluation harness

OpenAI GPT support is planned for future releases.

Still Have Questions?¶

Installation Help: Installation Guide
API Documentation: API Reference
Architecture Details: System Design
Bug Reports: GitHub Issues

Didn't find your answer? Open a GitHub Issue