BillAm

BillAm is an AI quoting agent that turns Nigerian client conversations into validated job briefs and draft quotes, with business knowledge, controlled workflows, and SME approval before sending.

Comment

Inspiration

Small businesses in Nigeria often lose potential customers before a job even starts.

A customer sends a message on WhatsApp or another messaging channel — sometimes incomplete, sometimes informal, sometimes in a mixture of English and Nigerian phrasing — and the business owner has to manually understand the request, ask follow-up questions, check their pricing, determine whether they can take the job, calculate a quote, and finally send it.

For a small business owner, that process is repetitive and time-consuming. More importantly, delays can mean lost customers or poorly priced jobs.

BillAm was inspired by a simple question:

What if an AI could handle the repetitive parts of that process while keeping the business owner in control of the decisions that matter?

That became the foundation of BillAm: an AI-powered client intake, clarification, quoting and SME approval workspace for Nigerian service businesses.

The AI handles the conversation and prepares the work, while the SME remains the final authority over the quote.

What it does

At a high level, BillAm turns an unstructured customer enquiry into a structured, reviewable business job.

A customer can simply describe what they need in natural language.

BillAm interprets the request, extracts the important information, and determines what is still missing.

If something is missing, it asks a focused clarification question. The autonomous clarification process is deliberately capped at two rounds. If the information still cannot be resolved, the job is escalated to the SME.

Once the brief is complete, BillAm uses the business's pricing information to prepare an itemized quote.

It also checks whether the requested scope is commercially feasible.

If the request is feasible, the quote moves to AWAITING_HUMAN_APPROVAL.

This is one of the most important parts of the product:

BillAm does not autonomously send the quote.

The SME can review and edit the draft, and only the SME can approve and send it.

The current backend implements this workflow through the job API, state machine, quote lifecycle and approval endpoint. [BillAm README]

What is already in the repository

There is already a foundation for two important future capabilities.

The repository contains:

  • knowledge-base JSON for multiple business types;
  • a KnowledgeStore;
  • Knowledge Base CRUD API routes;
  • an AvailabilityStore;
  • Availability CRUD/check APIs;
  • business-type configuration for six categories;
  • corresponding price catalogs.

However, these should not be presented as fully implemented customer-facing features yet.

The current agent tools are still centered on knowledge-base lookup, price-catalog lookup, job-state mutation and permitted messaging. Availability is currently represented as a separate API/store capability rather than a complete agent-driven booking/availability workflow. BillAm agent tools

So there is an important distinction:

The foundations exist in the codebase; the complete product capabilities are next.

How we built it

BillAm evolved through several stages rather than being designed as the final architecture from day one.

1. We started with a deterministic workflow

The first version established the core job lifecycle, state machine, data models, quote calculation and human approval boundary.

The workflow is represented through eight operational states:

IDLE → INGESTING → REASONING → CLARIFYING → NEEDS_SME_INPUT → AWAITING_HUMAN_APPROVAL → EXECUTED / FAILED_RETRY

This gave us something important early: an auditable workflow rather than an AI that could simply improvise its way through the entire business process.

2. We connected the workflow to the real backend

The dashboard moved away from purely scripted behavior and became connected to the real job and quote workflow.

That exposed actual integration problems: state mismatches, quote-data differences, retry behavior, missing fields and frontend assumptions that weren't actually true in the backend.

We fixed those issues and made the system represent real job states, conversations, extracted information, quotes, failures, escalation and approval.

3. We learned that the manual agent loop wouldn't scale

The original implementation used a manually orchestrated conversation loop.

That worked for proving the concept, but every new conversational behavior meant adding more procedural logic.

We wanted the agent to become more flexible without giving it unrestricted control.

So we moved to the Strands Agents SDK.

The new architecture separates responsibilities:

  • SOP — defines the agent's operating behavior.
  • Skills — define specialized behaviors.
  • Tools — expose controlled capabilities.
  • Hooks/guardrails — enforce runtime constraints.
  • State validation — remains deterministic in the application.
  • Persistence — keeps the job and conversation recoverable.

This changed the mental model from:

"We program every step the agent takes."

to:

"We define the rules and capabilities within which the agent operates."

4. We hardened the agent

We added persistent job/session handling, quote editing and approval, audit logging, retry handling, clarification protection, rate limiting and tone controls.

One particularly important lesson was preventing false completion.

The model might believe it has enough information, but that doesn't necessarily mean the information satisfies the business requirements.

So the application recomputes and validates the required fields rather than trusting the model's interpretation alone.

That gives us the core principle:

AI interprets. Code validates.

5. We built the foundations for expansion

The current repository already contains knowledge-base and pricing data for:

  • Event vendors
  • Caterers
  • Tailors
  • Photographers
  • Event planners
  • Equipment rental businesses

It also contains Availability and Knowledge Base API/store foundations.

But we deliberately distinguish between having the backend structures and having a finished product feature.

That distinction matters for where we are going next.

Challenges we ran into

The biggest challenge was finding the right boundary between AI flexibility and deterministic product behavior.

If we hard-code everything, the system becomes brittle.

If we allow the model to control everything, the system becomes unpredictable.

The Strands architecture gave us a middle ground: the agent can reason about what the customer means, while the application still controls state, validation, tool boundaries and approval.

Another major challenge was preventing the model from declaring a conversation complete simply because it thought a required field had been answered.

For example, "maybe around 100 people" shouldn't automatically satisfy a strict guest-count requirement.

Similarly, a technically complete request can still be commercially impossible.

So BillAm separates understanding the customer from certifying that the business requirements have been satisfied.

We also had to deal with the reality that model output isn't perfectly consistent. Field names, nesting and formatting can vary, so the system needed defensive parsing and validation rather than assuming the model would always return exactly what we expected.

Finally, we had to make the frontend reflect reality.

A sophisticated backend isn't useful if the dashboard shows a fake quote or hides the fact that a job needs SME intervention.

The UI therefore became part of the reliability problem, not just a presentation layer.

Accomplishments that we're proud of

We built more than a chatbot.

We built a controlled workflow around an AI agent.

BillAm can take an unstructured customer conversation, maintain context, extract business requirements, ask targeted questions, identify infeasible requests, generate a structured quote and bring that quote to a human approval boundary.

We are particularly proud of the separation between agent reasoning and deterministic business control.

The agent can be conversational and flexible without being allowed to silently bypass the business rules.

We're also proud of the architectural refactor.

Moving from a manually maintained orchestration loop to a Strands-based agent with an SOP, modular skills, bounded tools, persistence, rate limiting and guardrails gives us a stronger foundation for adding capabilities without continually rewriting the core conversation engine.

And the current repository has already been structured for growth: business-specific knowledge and pricing are separated into data/configuration rather than being hard-coded into a completely different agent for every business type.

What we learned

The biggest lesson was that the model should interpret, not certify.

Natural language is where AI is useful.

Business rules, state transitions, financial calculations and approval boundaries are where deterministic software should remain in control.

We also learned that a general-purpose agent isn't automatically a better product.

BillAm became more reliable when we constrained what the agent can do and made the important boundaries explicit.

We learned that human-in-the-loop isn't a limitation of BillAm.

It is part of the product value.

The SME doesn't have to manually conduct the entire customer conversation anymore, but they also don't have to surrender control over pricing or what ultimately gets sent to their customer.

And we learned that expanding an AI product isn't simply about adding more tools.

The underlying workflow needs to remain stable while capabilities are added around it.

What's next for Billam

The next phase is about taking the foundation we have today and expanding what BillAm can understand and act on.

1. Knowledge Base

The repository already has a Knowledge Base data model, store and CRUD API, as well as structured business knowledge.

The next step is turning that foundation into a real SME-facing Knowledge Base feature.

That means allowing businesses to provide their own information and making that information usable by the agent during customer conversations.

The goal is to move beyond a fixed BillAm knowledge file toward:

"This is what your business knows and offers."

2. ASR

ASR is not implemented in the current repository.

The current system is text-first, and the existing architecture documentation explicitly treats voice/ASR as outside the current scope.

The next phase will therefore introduce speech-to-text as another input modality.

Importantly, ASR should not create a separate business workflow.

It should simply turn a customer's voice input into usable text and feed that into the same intake, reasoning, clarification and quoting pipeline.

So architecturally:

Voice → transcription → existing BillAm agent flow

rather than:

Voice → completely separate agent.

3. Availability / Calendar

The repository already has the foundation for availability: an Availability Store, seeded availability records and API endpoints for creating, updating, deleting and checking blocked dates.

But the current agent flow does not yet make availability a first-class part of the customer conversation.

The next step is to connect it to the actual workflow.

That allows BillAm to reason about another critical question:

"Can this business actually take this job on the requested date?"

And the initial scope remains an internal availability/booking model, rather than integrating with Google Calendar or another external calendar service.

4. Expand beyond the initial business type

The repository already contains configuration and pricing data for six business categories.

The next step is to make that breadth a real product capability rather than simply having additional JSON files in the backend.

Different businesses should be able to have different:

  • required fields;
  • clarification rules;
  • knowledge;
  • pricing;
  • contingencies;
  • availability requirements.

But they should all run through the same underlying agent architecture.

That is where BillAm becomes much more powerful.

The long-term vision isn't an event-vendor quoting bot.

It's a reusable AI operating layer for service businesses.

The evolution is therefore:

Conversation → Understanding → Knowledge → Pricing → Availability → Human approval

while the underlying architecture remains:

AI for interpretation and orchestration.
Deterministic software for validation and control.
The SME for the final decision.

Built With

Share this project:

Updates

Submission history