F2F4 Forecast Copilot

Turns messy commercial data into a defensible forecast, with traceable decisions, risks, and evidence—powered by a deterministic core and controlled AI.

Comment

Inspiration

Part of the inspiration for Forecast Copilot came from learning about a Central American company that reportedly invested millions of dollars in an initiative to automate forecasting and build a planning copilot, but was unable to achieve the expected result.

That case stayed with me. If a company in Central America was willing to make an investment of that scale, the underlying problem was clearly real, urgent, and economically significant. Companies are not only looking for a more accurate forecast. They need to connect fragmented data, commercial assumptions, inventory, promotions, planning processes, and executive decisions without creating another long and expensive transformation project.

At the same time, AI-assisted development, modern language models, open-source forecasting tools, and tools such as Codex have significantly changed what a small team—or even a solo founder—can build. Capabilities that previously required large consulting and engineering programs can now be developed incrementally, tested against real workflows, and governed through a much smaller and more transparent architecture.

Forecast Copilot starts with a focused problem: turning imperfect commercial data into a defensible and traceable forecast. Forecasting is the entry point, not the final destination. The longer-term vision is to create an operating layer for commercial planning that connects forecasting with inventory risk, replenishment, allocation, promotions, S&OP, and executive decision-making.

The goal is not to replace business judgment or reproduce a multimillion-dollar transformation project. It is to create a thin but real product that demonstrates value quickly, preserves human control, and expands only after each capability has been validated.

What it does

Forecast Copilot turns imperfect commercial data into a controlled, traceable, and defensible forecasting process.

The current product foundation supports:

  • Creating and tracking forecasting runs
  • Uploading and registering source files
  • Executing a controlled run lifecycle
  • Persisting stages, timestamps, events, errors, and execution status
  • Retrying recoverable stages without losing the complete run
  • Cancelling executions safely
  • Registering artifacts with metadata and lineage
  • Listing and downloading authorized artifacts
  • Isolating files and results between runs
  • Replaying the workflow in a reproducible way
  • Applying security controls to uploads, downloads, paths, configuration, and logs

Every execution is identified by a run_id. This allows the system to connect the original input, processing stages, artifacts, decisions, errors, and final outputs.

The next product capabilities are designed to:

  1. Profile Excel, CSV, and database sources.
  2. Propose mappings from customer columns to a canonical commercial structure.
  3. Ask for human confirmation only when the meaning is ambiguous.
  4. Validate data quality before forecasting.
  5. Build a trusted commercial data layer.
  6. Execute multiple forecasting model families.
  7. Compare models through reproducible backtesting.
  8. Select or block the final forecast through deterministic rules.
  9. Explain risks, bias, assumptions, and limitations.
  10. Generate an executive brief supported by evidence.

The central product principle is simple:

AI can interpret, propose, challenge, and explain. The application validates, calculates, controls, persists, and publishes.

How I built it

I am building Forecast Copilot as a solo founder and product/program manager, using Codex as my technical building partner.

The product is local-first and is being developed in its own GitHub repository. Its main technical foundation includes:

  • Python
  • FastAPI
  • PostgreSQL
  • SQLAlchemy and database migrations
  • Filesystem-based artifact storage
  • Docker Compose
  • Pydantic contracts
  • Pytest
  • Git and GitHub
  • OpenAI integrations through a controlled client layer

The architecture deliberately separates two different systems.

Deterministic core

The deterministic core owns the critical business path:

  • Run orchestration
  • State transitions
  • Validation
  • Persistence
  • Data transformations
  • Forecast calculations
  • Backtesting
  • Quality gates
  • Artifact access
  • Security controls
  • Publication

These responsibilities live in the application repository and do not depend on free-form AI responses.

AI layer

The AI layer is designed to support:

  • Source understanding
  • Mapping proposals
  • Business-definition analysis
  • Demand-pattern interpretation
  • Forecast-strategy recommendations
  • Bias analysis
  • Evidence criticism
  • Risk explanation
  • Executive communication

AI outputs must follow structured contracts and pass deterministic validation before affecting the workflow.

Building with Codex

I did not use Codex to generate an entire application from a single prompt.

I created a controlled implementation process:

  1. Define one bounded task.
  2. Inspect the existing repository and documentation.
  3. Identify the expected behavior and acceptance criteria.
  4. Implement the smallest verifiable change.
  5. Run unit, integration, security, and regression tests.
  6. Record decisions, assumptions, risks, and evidence.
  7. Commit only after the task passes its gate.
  8. Continue to the next task without rebuilding working components.

The complete product has been decomposed into a structured backlog of 340 tasks across architecture, persistence, ingestion, data quality, forecasting, agents, frontend, observability, security, testing, and release.

This approach allows me to build incrementally while maintaining traceability and understanding the system I will eventually operate myself.

Challenges we ran into

Turning a proof of concept into a product

The first challenge was evolving an existing proof of concept without discarding working functionality or rebuilding the project from zero.

I had to identify which components already worked, establish a safe baseline, protect the existing flow, and introduce improvements through small, testable changes.

Keeping AI out of the critical path

It is easy to build an impressive demonstration where a language model appears to control everything.

It is much harder to build a product where AI is useful but cannot silently change state, approve a forecast, modify trusted data, access unauthorized files, or publish unsupported conclusions.

Defining that boundary became one of the most important architectural decisions in the project.

Security and traceability

Uploads, artifact downloads, paths, tenant boundaries, logs, configuration, and error messages can create serious risks.

The system required explicit validation of identifiers, authorized artifact access, path traversal protection, safe error handling, secret controls, and isolation between runs.

Persistent and recoverable execution

A real forecasting workflow cannot disappear when a process fails.

The product needed a formal state machine, persisted execution history, structured errors, retry policies, append-only events, and reproducible replay.

Building as a nontraditional technical founder

My background is in program and product management, not traditional software engineering.

I had to learn how to translate business requirements into schemas, repositories, services, tests, migrations, APIs, security controls, and executable acceptance criteria.

Codex accelerated the implementation, but I still had to retain responsibility for scope, architecture, validation, and product decisions.

Controlling scope

The long-term opportunity includes forecasting, inventory, replenishment, allocation, promotions, and S&OP.

The challenge was resisting the temptation to build everything at once.

I chose to build a thin but real foundation: the smallest system that can operate, preserve evidence, demonstrate value, and support the next product capabilities without unnecessary infrastructure.

Accomplishments that I'm proud of

I am proud that Forecast Copilot has moved beyond being only an idea, prompt, or architecture diagram.

The repository now contains an operational product foundation with:

  • A formal run lifecycle and state machine
  • Controlled creation, upload, execution, retry, cancellation, and timeline flows
  • Persistent execution metadata and events
  • Structured and recoverable errors
  • Secure artifact registration and downloads
  • Protection against unauthorized paths and file access
  • Reproducible workflow replay
  • Isolation between independent runs
  • Automated lifecycle, regression, access, and security testing
  • Versioned technical and product documentation
  • Decision and assumption logs
  • A construction backlog that maps product capabilities to executable tasks

I am also proud that the system is designed to remain operable by its founder.

The objective is not to create an architecture that only a large engineering team can understand. Setup, execution, testing, recovery, and validation must remain clear enough for me to run and demonstrate the product directly.

Most importantly, Forecast Copilot represents a product opportunity originating in Central America.

It addresses a problem for which companies have already shown a willingness to invest significant amounts of money, but approaches it through a smaller, progressive, evidence-based product strategy.

What I learned

The most important lesson was that AI-assisted development is not the same as asking AI to build a product autonomously.

AI-assisted development becomes reliable when the founder controls:

  • The problem being solved
  • Product scope
  • System boundaries
  • Contracts
  • Acceptance criteria
  • Testing
  • Architectural authority
  • Evidence
  • Release decisions

Codex was most valuable when used as a disciplined implementation partner rather than an unrestricted code generator.

I also learned that documentation is not separate from implementation. In a solo-founder environment, documentation functions as operational memory. It prevents architectural drift, reduces repeated analysis, and allows each new task to start from verified context.

Another important lesson was that forecast accuracy alone is not the final value.

A forecast becomes useful when a person can answer:

  • Which data was used?
  • What was changed?
  • Why did this model win?
  • What limitations remain?
  • Where is the risk?
  • What decision should be made next?
  • Can the result be defended in front of the business?

Finally, I learned that modern AI development tools can dramatically reduce the barrier to building sophisticated products—but they do not eliminate the need for product judgment, architecture, validation, security, and accountability.

What's next for F2F4 Forecast Copilot

The next construction stage is to complete the path from uploaded source files to a selected and explainable forecast.

Product development

The immediate roadmap includes:

  • Source profiling for Excel, CSV, and controlled database connections
  • Assisted semantic mapping
  • Human review for ambiguous mappings
  • Canonical commercial data contracts
  • Data-quality rules and Gate 1
  • Trusted Gold commercial tables
  • Pre-forecast semantic cubes
  • Series profiling
  • A registry of forecasting models
  • Baselines, classical time-series models, intermittent-demand models, machine-learning models, and ensembles
  • Reproducible backtesting
  • Forecast metrics and uncertainty intervals
  • Deterministic model selection through Gate 2
  • Bias and exception analysis
  • Evidence-based executive briefs
  • Product views for operators, planning leaders, and executives

Business validation

The product also needs to move from technical proof to customer evidence.

The next business steps are:

  • Interview demand-planning and commercial-planning leaders
  • Validate the primary user and buyer
  • Test the product with representative commercial datasets
  • Measure hours saved per planning cycle
  • Measure the reduction in manual reconciliation and repeated work
  • Compare forecast performance against simple baselines
  • Validate whether companies will pay for a controlled pilot
  • Run a limited regional pilot before expanding integrations

Long-term vision

Forecast Copilot will begin with forecasting, but the final opportunity is the commercial decision cycle.

A completed forecast should prepare the next questions:

  • What should the company buy?
  • How much should it buy?
  • When should it buy?
  • Where should inventory be allocated?
  • Which products or locations are at risk?
  • Which promotions or assumptions changed the plan?
  • What should be escalated to S&OP or executive leadership?

The long-term vision is a modular commercial-planning platform that connects those decisions while keeping business rules, data, evidence, and human approval under the customer's control.

The goal is not to recreate an expensive transformation program.

The goal is to demonstrate that a thin, operational, AI-enabled product can solve one real problem, prove measurable value, and expand capability by capability.

Built With

Share this project:

Updates