Weekend Agent Challenge: Ledger Clerk

This document reports on the design and construction of ledger-clerk, an expense-ledger agent produced for the Weekend Agent Challenge. The agent presents a minimal web form, records each submitted expense durably in Amazon DynamoDB, and renders a running total. The runtime is the Python standard-library HTTP server. The service does not employ CloudFormation and is operated locally by a single user. This report covers the agent's function and audience, its construction and AWS dependencies, the single detail introduced to improve the operating experience, and the evidence that the detail performs as intended.

ledger-clerk accepts expense entries — an amount and a short description — through a browser form served at 127.0.0.1:8073, persists each entry, and returns the updated ledger and running total on every submission.

The intended user is a single individual who requires durable, low-ceremony expense tracking without a spreadsheet, an account, or a subscription. The agent is explicitly scoped to single-user local operation. Authentication, multi-tenant isolation, currency conversion, and reporting beyond a running total are declared non-goals.

The HTTP layer is implemented with Python's http.server module and binds to 127.0.0.1 only, in keeping with the principle of least exposure. No third-party web framework is introduced.

The persistence layer uses Amazon DynamoDB, accessed through boto3. A single table, keyed by a string id, is created on first use with PAY_PER_REQUEST (on-demand) billing. The agent requires the IAM permissions dynamodb:CreateTable, dynamodb:DescribeTable, dynamodb:PutItem, and dynamodb:Scan. DynamoDB was selected because it provides durable persistence with no provisioned, always-on compute, and because single-user volumes fall within the AWS Free Tier.

The architecture is summarised as follows:

The agent is a single Python module, server.py, with boto3 as its soledependency. The absence of CloudFormation is deliberate: a local process incursno idle cost and requires no deployment or teardown procedure.

The experiential decision of record is the first-run configuration dialogue combined with uniformly instructive error handling. On first start, the operator is prompted once for region, table name, and an optional profile; these values are written to ~/.ledger-clerk.ini at file mode 0600 and are not requested again. The user is therefore never required to edit source, set environment variables, or consult documentation to begin.

Correspondingly, every failure path returns a plain-language remedy rather than a diagnostic trace. Absent credentials direct the operator to aws configure. An authorisation failure names the specific IAM permission required. A rendered form is returned in every case; the operator is not confronted with a stack trace at any point.

The detail was verified by adversarial operation. The agent was started with no credentials present; it reported the absence in one sentence and directed the operator to configure them, rather than terminating with an exception. Credentials were then supplied with an over-restrictive policy omitting dynamodb:CreateTable; the agent named the missing permission exactly. Upon correction, an expense was submitted and the running total updated on the same request, confirming the persistence and rendering paths. The experience from a cold start to a first recorded entry required no reference to this document.

ledger-clerk demonstrates that a durable, cost-aware agent can be constructed from the Python standard library and a single managed service, with no deployment surface. The configuration dialogue and the instructive error contract together constitute a measurably smoother first run than an unconfigured script would provide.

Future work, were the non-goals to be relaxed, would address authentication and categorised reporting; both are presently out of scope by design.

Repository: https://github.com/ssudeshna024/ledger-clerk-Service-Specification

Invocation: pip install -r requirements.txt; python server.py;
open 127.0.0.1:8073.