A deterministic, rule-based Python service that turns messy human
datetimes like "16 Apr 2026 10 PM" or
"30 min from now" into a single canonical
YYYY-MM-DDTHH:MM:SS.sssZ string — wrapped in a JSON
envelope with machine-readable status codes.
Chatbot-DateTime is a small, dependency-light Python service for teams who
need to accept messy human datetime input and feed a
single canonical ISO 8601 UTC string to downstream systems.
It runs offline, respects India-first defaults (Asia/Kolkata, DMY),
enforces a [now, now + 3 days] validity window, and returns
numeric status codes so consuming applications can branch programmatically.
Both a CLI and a FastAPI REST interface ship in the box.
Nine reasons it sits quietly between your users and your database.
Every datetime returned as YYYY-MM-DDTHH:MM:SS.sssZ — ISO 8601 UTC with 3-digit milliseconds, enforced by a final regex check (^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$) so no response ever leaves the service in a looser format.
Every metadata field is a {code, label} pair. 19 codes total across 4 tables (ASSUMPTION, TREATED_AS, VALID_WINDOW, ERROR) live in config.py — branch on integers, not translated strings.
Timezone Asia/Kolkata (UTC +05:30), date order DMY. Both are constants in config.py (DEFAULT_TIMEZONE, DEFAULT_DATE_ORDER) and overridable per request via --tz / --date-order.
Default [now, now + 3 days] driven by MAX_FUTURE_DAYS in config.py. Past dates pass through flagged with treated_as: past; anything beyond the window is rejected with error code 11 — out_of_range_future.
A dedicated _count_datetimes() pass uses dateparser.search_dates to detect ranges or multiple timestamps and raises MultipleDatetimesFound → error code 10 — multiple_datetimes. The contract stays strict by design.
REST API (POST /parse, GET /health) via FastAPI with auto-generated OpenAPI docs, plus a CLI with --tz, --date-order, and --serve flags. Both share the same parser core.
Four Draft 2020-12 schemas — INPUT, OUTPUT_SUCCESS, OUTPUT_ERROR, LLM_RESPONSE — in validation/schemas.py validate every payload at the boundary. Breakage is caught before it reaches a consumer.
Pluggable auth via env vars DTB_LLM_URL, DTB_LLM_API_TOKEN, DTB_LLM_USERNAME, DTB_LLM_PASSWORD. Provider-neutral (default template targets claude-opus-4-6) with a strict response schema and safety checks around the returned datetime.
Runs on modest hardware — roughly 5 GB RAM and a 4-core CPU (Intel or ARM, < 1.5 GHz is enough) for a single user in regular use. No internet required*.
Tested on an ARM cloud VM (arm64); runs equivalently on low-end Intel/AMD machines. * Except when the optional LLM fallback is enabled.
The Python ecosystem already has several natural-language date tools — dateparser (200+ locales, general-purpose), parsedatetime (future relative dates), timefhuman (ranges & lists), recurrent (RRULE generation), and dateutil (formatted dates). Chatbot-DateTime is deliberately narrower: one datetime in, one strict ISO 8601 UTC string out, wired for production pipelines where the contract matters more than feature breadth.
Drop-in service for normalizing user-submitted datetimes before they hit your database.
Where dateparser alone returns a Python datetime you still have to
format, this returns the canonical ISO-8601 UTC string already validated against a published
JSON schema — safe to store, index, or forward as-is.
Originally built to track
GST portal scheduled-downtime windows
(typically 2–6 hour rolling maintenance slots announced with short notice). The same
[now, now + 3 days] pattern fits any short-window schedule: filing deadlines,
e-invoice IRN windows, bank cut-off times, exchange notice boards.
Handles typos and sloppy formats that standard parsers reject outright — apostrophe years
(25/Apr/'26), two-digit years, space-separated tokens, DMY/MDY ambiguity. If
the rule-based pass still can't decide, the optional LLM fallback steps in with a
schema-validated response. No hand-crafted regex tables per locale.
REST (POST /parse, GET /health) + OpenAPI 3.1 spec + 19 numeric
status codes across 4 tables → trivial to wire into an existing pipeline. Branch on
integers, not translated strings; surface assumptions (timezone_india_default,
date_order_dmy) back to the user explicitly.
Turn free-text columns in a CSV / spreadsheet / ticket export into clean ISO-8601 UTC values in a single pass. The strict output regex makes downstream parquet / BigQuery / Postgres loads predictable — no mixed timezones, no mystery millisecond precision.
Slot-booking, appointment reminders, SIP / EMI due-date collectors — anywhere a user types
"next Tuesday at 10" and you need a canonical timestamp your billing / notification
engine can act on. India-first defaults (Asia/Kolkata, DMY) mean fewer
config-per-tenant workarounds for the common case.
References & related tools: dateparser docs · dateparser (GitHub) · parsedatetime · timefhuman · recurrent · python-dateutil · GST Developer Portal
Calls the live hosted API. Falls back to an in-browser parser if the API is unreachable.
JSON response
// Press "Parse" to see outputClone, install, parse. Under a minute on a warm laptop.
# Clone
git clone https://github.com/fyaz6194/Chatbot-DateTime.git
cd Chatbot-DateTime
# Virtual env + deps
python -m venv .venv
source .venv/Scripts/activate # Windows git-bash
# or: .\.venv\Scripts\Activate.ps1 # PowerShell
# or: source .venv/bin/activate # macOS/Linux
pip install -r datetime_bot/requirements.txt
# Parse once from the CLI
python -m datetime_bot "16 Apr 2026 10:00 PM"
# Or run the REST API
python -m datetime_bot --serve
# -> http://127.0.0.1:8000/docs (Swagger UI, local only)
The Swagger UI at /docs is served by FastAPI at runtime — it only
exists while the server is running locally. The underlying OpenAPI spec is
committed to the repo at
datetime_bot/openapi.json ↗
and can be loaded into any OpenAPI viewer (e.g.
editor.swagger.io)
to get the same interactive docs without running the server.
Hit the REST interface, get a strict envelope back.
# Request
curl -X POST http://127.0.0.1:8000/parse \
-H "Content-Type: application/json" \
-d '{"text": "16 Apr 2026 10:00 PM"}'// Response (200)
{
"datetime": "2026-04-16T16:30:00.000Z",
"assumption": [
{"code": 1, "label": "default_timezone_india"},
{"code": 2, "label": "default_date_order_dmy"}
],
"treated_as": {"code": 2, "label": "within_window"},
"valid_window": {
"code": 1, "label": "in_window",
"start": "2026-04-15T22:52:27.521Z",
"end": "2026-04-18T22:52:27.521Z"
}
}Every metadata field carries a stable numeric code. Branch on these, not on labels.
Chatbot-DateTime leans on a small group of excellent open-source tools. Help us develop this project further — a win-win for every side: users get a more reliable parser, contributors get credit and a hardened codebase, and the upstream tools listed below get real-world feedback from another production user.
AZUX Solutions builds future-proof, open-technology tooling for business accounting and day-to-day operations — grounded in first-hand operator experience running multi-branch retail, not just academic theory.
AZUX Solutions started with a practical problem. The founder began as an accountant with only light programming knowledge, running the books for a family business with six branches. Off-the-shelf point-of-sale software didn't fit the way the business actually worked — licenses capped features, add-ons were expensive, and the vendor's roadmap was never the business's roadmap.
So he built one. A working POS system serving all six branches, learning in the open, shipping for real users every day — the kind of feedback loop no classroom can simulate.
AZUX Solutions was founded in mid-2017 out of that work. The founder later relocated to Canada, completed a Diploma of Computer Science, and is currently pursuing a Bachelor of Applied Science in Computer Engineering — deepening the engineering foundations needed to build the next generation of business tooling from the ground up. The company continues to operate with one foot in India (where the original six-branch business runs) and one in Canada (where new engineering work happens).
AZUX Solutions has spent the last nine years quietly building and learning across the full stack of small-business operations software:
The long-term mission of AZUX Solutions is to contribute meaningfully to the accounting world through computation — shipping advanced accounting software that treats the books as a first-class computational workload, not a spreadsheet afterthought.
Concretely, that means marrying the operator know-how of running a real multi-branch business with the engineering rigour of formal computer science: deterministic rule-based cores (like Chatbot-DateTime), open public schemas, machine-readable status codes, and the automation layer that lets small and mid-sized businesses keep pace with the largest enterprises — without paying enterprise-tier licensing.
Chatbot-DateTime is source-visible but not open-source.
You may read the code and submit pull requests to
improve it, but you may not use it in your own projects, products,
or services. See LICENSE in the repository for the full terms.
This is a well-worn path in infrastructure software. Projects like SQLite (started restrictive, now public domain), Redis, MongoDB, and Elasticsearch (relicensed to guard against unfair cloud re-hosting), and modern BSL-style licenses used by HashiCorp, CockroachDB, and Sentry (source-visible today, auto-open after a set time) all followed the same pattern: be visible and contributable from day one, but keep reuse restricted until the project is ready to carry the weight of production users.
References: SQLite copyright · Redis relicense announcement · MongoDB SSPL · Elastic license change · BSL 1.1 (MariaDB) · HashiCorp → BSL · CockroachDB relicense · Functional Source License (Sentry)
Chatbot-DateTime is at that same early stage. Before unrestricted reuse can be responsibly permitted, four layers of validation and feature work still need to be closed out:
Read, learn, and contribute via pull requests. No production reuse.
Test coverage, cybersecurity review, performance benchmarks, baseline features.
Once hardened, the license moves toward a permissive open-source tier (BSL-style time-release or outright MIT/Apache on the stable surface).
Until the items above are complete, the source-visible / no-external-use license protects downstream users from depending on behavior that is still subject to change — and protects the project from being forked into unmaintainable derivatives before its contract is stable.