Skip to content

Plus One v0.1.0

Latest
Latest

Choose a tag to compare

View all tags
@adamraziv adamraziv released this 21 Jul 04:36
v0.1.0
4453421
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

The first release of Plus One: an open-source, self-hosted household finance agent designed for couples.

Plus One accepts natural-language requests through chat channels while keeping financial writes behind deterministic validation, explicit confirmation, PostgreSQL constraints, and verified readback.

Highlights

Conversational accounting

  • List household accounts and transactions.
  • Record expenses and income through natural, multi-turn conversations.
  • Create missing accounts or transaction categories with confirmation.
  • Preserve transaction details while resolving missing information.
  • Understand relative dates such as “today” and “yesterday” using the household timezone.
  • Handle multiple currencies, currency precision, assets, liabilities, income, and expenses.

Checked financial mutations

Every financial write follows a maker-checker flow:

  1. An agent proposes the change.
  2. A checker validates the proposal.
  3. The user confirms when required.
  4. Deterministic services execute the mutation.
  5. Plus One verifies the committed result before reporting success.

Accounting records remain append-only, while idempotency and replay protection prevent duplicate commits.

Reliable conversation handling

  • Durable conversation state across follow-up messages and restarts.
  • Safe recovery after clarification, timeout, or interrupted execution.
  • Duplicate Telegram updates are deduplicated—even across gateway restarts.
  • Bounded delegation and inbound deadlines prevent runaway requests.
  • Internal tool details and database identifiers are filtered from user-facing responses.

Self-hosted runtime

  • PostgreSQL-backed accounting, runtime state, and Mastra memory.
  • Telegram pairing and production channel intake.
  • Production health and readiness endpoints.
  • Operator CLI for starting, stopping, inspecting, and monitoring the gateway.
  • Privacy-conscious rotating logs containing operational metadata rather than financial payloads or conversation bodies.

Getting started

Requirements:

  • Node.js 22.13 or newer
  • pnpm 10.20.0
  • Docker
  • An LLM API key
pnpm install
cp .env.example .env
pnpm db:up
pnpm db:migrate
pnpm db:verify
pnpm install:cli
plus-one

Use plus-one status, plus-one stop, and plus-one live to operate the gateway.

Reliability

This release includes unit, database, integration, and live-service acceptance coverage. The accounting acceptance matrix exercises:

  • Multi-turn transaction entry
  • Missing-category continuation
  • Confirmation, cancellation, and replay
  • Invalid and corrected amounts or dates
  • Currency scale rules
  • Household timezone boundaries
  • Asset and liability posting directions
  • Gateway readiness and graceful shutdown
  • Telegram duplicate delivery across restart

Current scope

v0.1.0 establishes the core runtime and accounting safety model. Plus One is still an early-stage project: conversation ingress is channel-only, and the terminal interface is an operator console rather than a chat client.

Assets 2
Loading