parsely-dip 0.0.2__tar.gz → 0.0.4__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (28) hide show
  1. {parsely_dip-0.0.2 → parsely_dip-0.0.4}/PKG-INFO +207 -6
  2. parsely_dip-0.0.2/src/parsely_dip.egg-info/PKG-INFO → parsely_dip-0.0.4/README.md +931 -753
  3. {parsely_dip-0.0.2 → parsely_dip-0.0.4}/pyproject.toml +3 -1
  4. {parsely_dip-0.0.2 → parsely_dip-0.0.4}/src/parsely_dip/__init__.py +20 -11
  5. parsely_dip-0.0.4/src/parsely_dip/cli/main.py +118 -0
  6. {parsely_dip-0.0.2 → parsely_dip-0.0.4}/src/parsely_dip/engine/nlp.py +8 -2
  7. {parsely_dip-0.0.2 → parsely_dip-0.0.4}/src/parsely_dip/engine/regex.py +12 -4
  8. {parsely_dip-0.0.2 → parsely_dip-0.0.4}/src/parsely_dip/engine/registry.py +14 -2
  9. {parsely_dip-0.0.2 → parsely_dip-0.0.4}/src/parsely_dip/engine/stanza_service.py +4 -1
  10. parsely_dip-0.0.4/src/parsely_dip/intents/day.py +376 -0
  11. parsely_dip-0.0.4/src/parsely_dip/intents/time.py +33 -0
  12. parsely_dip-0.0.2/README.md → parsely_dip-0.0.4/src/parsely_dip.egg-info/PKG-INFO +954 -732
  13. {parsely_dip-0.0.2 → parsely_dip-0.0.4}/src/parsely_dip.egg-info/SOURCES.txt +1 -0
  14. {parsely_dip-0.0.2 → parsely_dip-0.0.4}/src/parsely_dip.egg-info/requires.txt +2 -0
  15. parsely_dip-0.0.2/src/parsely_dip/cli/main.py +0 -23
  16. parsely_dip-0.0.2/src/parsely_dip/intents/time.py +0 -19
  17. {parsely_dip-0.0.2 → parsely_dip-0.0.4}/LICENSE +0 -0
  18. {parsely_dip-0.0.2 → parsely_dip-0.0.4}/setup.cfg +0 -0
  19. {parsely_dip-0.0.2 → parsely_dip-0.0.4}/src/parsely_dip/cli/__init__.py +0 -0
  20. {parsely_dip-0.0.2 → parsely_dip-0.0.4}/src/parsely_dip/engine/__init__.py +0 -0
  21. {parsely_dip-0.0.2 → parsely_dip-0.0.4}/src/parsely_dip/engine/splitter.py +0 -0
  22. {parsely_dip-0.0.2 → parsely_dip-0.0.4}/src/parsely_dip/intents/__init__.py +0 -0
  23. {parsely_dip-0.0.2 → parsely_dip-0.0.4}/src/parsely_dip/intents/scrum.py +0 -0
  24. {parsely_dip-0.0.2 → parsely_dip-0.0.4}/src/parsely_dip/intents/weather.py +0 -0
  25. {parsely_dip-0.0.2 → parsely_dip-0.0.4}/src/parsely_dip/patterns/__init__.py +0 -0
  26. {parsely_dip-0.0.2 → parsely_dip-0.0.4}/src/parsely_dip.egg-info/dependency_links.txt +0 -0
  27. {parsely_dip-0.0.2 → parsely_dip-0.0.4}/src/parsely_dip.egg-info/entry_points.txt +0 -0
  28. {parsely_dip-0.0.2 → parsely_dip-0.0.4}/src/parsely_dip.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: parsely-dip
3
- Version: 0.0.2
3
+ Version: 0.0.4
4
4
  Summary: PARSELY-DIP: Deterministic Intent Parser — RegEx and NLP pipeline for intent recognition
5
5
  Author-email: George Butiri <george@iseestudios.com>
6
6
  License: Proprietary
@@ -17,6 +17,8 @@ Requires-Dist: stanza>=1.5
17
17
  Requires-Dist: requests>=2.28
18
18
  Requires-Dist: python-dotenv>=1.0
19
19
  Requires-Dist: flask>=3.0
20
+ Requires-Dist: word2number>=1.1
21
+ Requires-Dist: num2words>=0.5
20
22
  Dynamic: license-file
21
23
 
22
24
  # PARSELY-DIP
@@ -393,6 +395,8 @@ def tell_time():
393
395
  | Intent | File | What It Does |
394
396
  |--------|------|-------------|
395
397
  | `tell_time` | `intents/time.py` | Returns current time in 24-hour format |
398
+ | `check_ability_time` | `intents/time.py` | Ability check — verifies `tell_time` handler exists and works, responds with usage hint |
399
+ | `tell_day` | `intents/day.py` | Returns day of the week for any date — today, relative dates, holidays (fixed and moving), numeric dates |
396
400
  | `tell_weather` | `intents/weather.py` | Returns weather via OpenWeatherMap API (requires `WEATHER_API_KEY` in `.env`) |
397
401
  | `show_current_card` | `intents/scrum.py` | Shows active scrum cards from SQLite database |
398
402
  | `read_current_card` | `intents/scrum.py` | Same data as show, but intended for LLM to summarize |
@@ -427,7 +431,8 @@ parsely-dip/
427
431
  stanza_service.py — Stanza NLP Flask service (port 5013)
428
432
  intents/
429
433
  __init__.py — Auto-imports all intent modules
430
- time.py — tell_time handler
434
+ time.py — tell_time, check_ability_time handlers
435
+ day.py — tell_day handler (holidays, relative dates, moving holidays)
431
436
  weather.py — tell_weather handler (OpenWeatherMap API)
432
437
  scrum.py — show_current_card, read_current_card handlers
433
438
  patterns/
@@ -439,6 +444,138 @@ parsely-dip/
439
444
 
440
445
  ---
441
446
 
447
+ ## Showcase: The `tell_day` Intent
448
+
449
+ The `tell_day` intent demonstrates the full power of the three-tier pipeline with dynamic parameter passing. One handler answers 15+ question forms — from simple regex catches to complex NLP-parsed queries with moving holiday calculators.
450
+
451
+ ### What It Handles
452
+
453
+ ```
454
+ >>> what day is it
455
+ Today is Sunday, March 29, 2026.
456
+
457
+ >>> what day will it be tomorrow
458
+ Tomorrow will be Monday, March 30, 2026.
459
+
460
+ >>> what day will it be in three days
461
+ in 3 days it will be Wednesday, April 01, 2026.
462
+
463
+ >>> what day is April Fools
464
+ April Fool's Day will be Wednesday, April 01, 2026.
465
+
466
+ >>> what day is on 4/1
467
+ 4/1/2026 will be Wednesday, April 01, 2026.
468
+
469
+ >>> when is easter
470
+ Easter will be Sunday, April 05, 2026.
471
+
472
+ >>> when is thanksgiving
473
+ Thanksgiving will be Thursday, November 26, 2026.
474
+
475
+ >>> when is the next 4th of July
476
+ Independence Day will be Saturday, July 04, 2026.
477
+
478
+ >>> when is mothers day
479
+ Mother's Day will be Sunday, May 10, 2026.
480
+
481
+ >>> when is mlk day
482
+ Martin Luther King Jr. Day was Monday, January 19, 2026.
483
+
484
+ >>> what day is christmas
485
+ Christmas Day will be Friday, December 25, 2026.
486
+
487
+ >>> what day is memorial day
488
+ Memorial Day will be Monday, May 25, 2026.
489
+
490
+ >>> what day is labor day
491
+ Labor Day will be Monday, September 07, 2026.
492
+ ```
493
+
494
+ ### How It Works
495
+
496
+ **Layer 1 (RegEx)** catches the simplest forms in microseconds:
497
+
498
+ ```
499
+ what\s+day\s+is\s+it(\s+today)?\?? => tell_day
500
+ what('s|\s+is)\s+today('s)?\s+day\?? => tell_day
501
+ ```
502
+
503
+ These fire without the Stanza service. No NLP needed. The handler receives no context and returns today's date.
504
+
505
+ **Layer 2 (NLP)** catches everything else. Three patterns cover all the complex forms:
506
+
507
+ ```json
508
+ {"sentence_type": ["SBARQ", "SBAR"], "words": [
509
+ {"lemma": "what", "dep": "det"}, {"lemma": "day", "dep": "nsubj"}, {"lemma": "be", "dep": "cop"}
510
+ ]}
511
+ ```
512
+
513
+ This matches "what day is [X]" — holidays, dates, any noun phrase after the copula.
514
+
515
+ ```json
516
+ {"sentence_type": ["SBARQ", "SBAR"], "words": [
517
+ {"lemma": "what", "dep": "det"}, {"lemma": "day", "dep": "root"}, {"lemma": "be", "dep": ["cop", "aux"]}
518
+ ]}
519
+ ```
520
+
521
+ This matches "what day will it be [X]" — future tense with relative dates, "in three days", "tomorrow".
522
+
523
+ ```json
524
+ {"sentence_type": "SBARQ", "words": [
525
+ {"lemma": "when", "dep": ["root", "advmod"]}, {"lemma": "be", "dep": "cop"}
526
+ ]}
527
+ ```
528
+
529
+ This matches "when is [X]" — the broadest form. Catches any "when is easter", "when is the next thanksgiving", "when is christmas".
530
+
531
+ **Dynamic Parameter Passing:** When the NLP layer matches, it passes the full parsed word list to the handler as a `context` dict. The handler's `extract_date_reference()` function reads the words, skips structural tokens (what, day, is, it, be, will, when, the), and assembles the remaining meaningful words into a date reference string. Written numerals are converted via `word2number` — "three" becomes `3`. The reference string is then resolved by `resolve_date()`.
532
+
533
+ ### Date Resolution
534
+
535
+ The `resolve_date()` function handles six categories of date references:
536
+
537
+ **Relative dates:** "today", "tomorrow", "yesterday" — simple offset from `datetime.now()`.
538
+
539
+ **Relative offsets:** "in 3 days", "in five days" — parsed from "in N days" pattern, numerals converted via `word2number`.
540
+
541
+ **Weekday names:** "wednesday", "next wednesday" — finds the next occurrence of that weekday.
542
+
543
+ **Fixed holidays:** Christmas (Dec 25), Halloween (Oct 31), Independence Day (Jul 4), Valentine's Day (Feb 14), and 8 more — stored as `(month, day)` tuples with extensive aliases (xmas, 4th of july, april fools, etc.).
544
+
545
+ **Moving holidays:** Computed per year, not stored:
546
+
547
+ | Holiday | Algorithm |
548
+ |---------|-----------|
549
+ | Easter | Anonymous Gregorian computus |
550
+ | Thanksgiving | 4th Thursday of November |
551
+ | Memorial Day | Last Monday of May |
552
+ | Labor Day | 1st Monday of September |
553
+ | MLK Day | 3rd Monday of January |
554
+ | Presidents Day | 3rd Monday of February |
555
+ | Mother's Day | 2nd Sunday of May |
556
+ | Father's Day | 3rd Sunday of June |
557
+ | Columbus Day | 2nd Monday of October |
558
+
559
+ **Numeric dates:** "4/1", "12-25", "4/1/2026" — parsed with `/` or `-` separator.
560
+
561
+ **Ordinal patterns:** "4th of July", "1st of December" — regex extraction of day number + month name.
562
+
563
+ ### Tense and "Next" Handling
564
+
565
+ The response uses correct tense based on whether the resolved date is in the past, present, or future:
566
+
567
+ - Past: "Martin Luther King Jr. Day **was** Monday, January 19, 2026."
568
+ - Present: "Christmas Day **is today**, Thursday, December 25, 2026."
569
+ - Future: "Easter **is** Sunday, April 05, 2026."
570
+
571
+ The "next" prefix (from "when is the **next** 4th of July") forces the date to roll forward to the next occurrence if the date has already passed this year.
572
+
573
+ ### The Handler
574
+
575
+ All of this logic lives in one file — `intents/day.py`. The `@intent('tell_day')` handler is 10 lines. The rest is `resolve_date()` (40 lines), holiday data (30 lines), and the moving holiday calculators (50 lines). No LLM. No API calls. No token cost. Pure `datetime` arithmetic.
576
+
577
+ ---
578
+
442
579
  ## Hook Integration
443
580
 
444
581
  PARSELY-DIP is designed to run as a Claude Code `UserPromptSubmit` hook. The hook intercepts the user's message, runs it through the pipeline, and either handles it deterministically or lets the LLM process it.
@@ -505,13 +642,33 @@ python -m parsely_dip.engine.stanza_service
505
642
  | `/process_syntactic_parsing` | POST | Parse text, return words with POS/dependency/constituency |
506
643
  | `/debug_parse` | POST | Raw parse data for debugging sentence structure |
507
644
 
508
- ### Interactive Mode
645
+ ### CLI Commands
646
+
647
+ All commands run through the `parsely` entry point:
648
+
649
+ | Command | Description |
650
+ |---------|-------------|
651
+ | `parsely start` | Start the Stanza NLP service (foreground, Ctrl+C to stop) |
652
+ | `parsely --chat` | Interactive chat — runs prompts through the full pipeline, shows responses |
653
+ | `parsely --test` | Structure explorer — shows constituency trees, POS tags, dependency relations |
654
+ | `parsely "prompt"` | Single query — returns response or "No match" |
655
+
656
+ **`parsely start`** launches the Stanza NLP service on port 5013. Required for NLP pattern matching and `--test` mode. RegEx matching works without it.
657
+
658
+ **`parsely --chat`** is the user-facing mode. Type a prompt, see the response. Patterns hot-reload from disk — edit a `.patterns` or `_nlp.json` file and the next query picks up the changes without restarting.
509
659
 
510
- ```bash
511
- python -m parsely_dip.engine.stanza_service --chat
512
660
  ```
661
+ >>> could you please tell me the time
662
+ Yes, just ask 'what time is it?' or 'what's the time?'
513
663
 
514
- Opens an interactive prompt where you can type sentences and see their full parse structure — constituency trees (inline and visual), POS tags, and dependency relations. Useful for building new NLP patterns.
664
+ >>> what time is it?
665
+ 06:12
666
+
667
+ >>> hello there
668
+ [No match — would fall through to LLM]
669
+ ```
670
+
671
+ **`parsely --test`** is the developer-facing mode. Type a sentence, see its full parse structure. Requires the service running (`parsely start` in another terminal).
515
672
 
516
673
  ```
517
674
  >>> What's your name?
@@ -545,6 +702,10 @@ Opens an interactive prompt where you can type sentences and see their full pars
545
702
  ?
546
703
  ```
547
704
 
705
+ ### Hot Reload
706
+
707
+ Pattern files (`.patterns` and `_nlp.json`) are checked for changes on every `parse()` call by comparing file modification times. If a file was saved since the last load, patterns reload automatically. No service restart, no `--chat` restart — just save the file and type the next query.
708
+
548
709
  ### Security
549
710
 
550
711
  - Localhost only (127.0.0.1) — rejects non-local requests
@@ -577,6 +738,26 @@ NLP patterns define grammatical structures that map to intents. Unlike regex (ex
577
738
  }
578
739
  ```
579
740
 
741
+ ### Example: Ability Check Pattern
742
+
743
+ The `check_ability_time` pattern demonstrates modal verb + action verb + noun slot matching. It catches "can you tell me the time?", "could you please give me the time", "could you possibly show me the time" — all with one pattern:
744
+
745
+ ```json
746
+ {
747
+ "intent": "check_ability_time",
748
+ "nlp": {
749
+ "sentence_type": "SQ",
750
+ "words": [
751
+ {"lemma": ["can", "could"], "pos": "AUX", "dep": "aux", "required": true},
752
+ {"lemma": ["tell", "give", "show", "get"], "pos": "VERB", "dep": "root", "required": true},
753
+ {"lemma": "time", "pos": "NOUN", "dep": "obj", "head_lemma": "tell", "required": true}
754
+ ]
755
+ }
756
+ }
757
+ ```
758
+
759
+ The pattern requires three things: a modal AUX (can/could), an action VERB (tell/give/show/get) as root, and the NOUN "time" as its object. Everything else — "you", "me", "the", "please", "possibly" — is not in the pattern and gets ignored. The sentence type SQ (yes/no question) distinguishes this from SBARQ (wh-question like "what time is it?"), which routes to `tell_time` instead.
760
+
580
761
  ### Matching Modes
581
762
 
582
763
  - **Exact Word Match** — `word` specified: match that exact word in that grammatical position
@@ -616,6 +797,8 @@ dependencies = [
616
797
  "requests>=2.28",
617
798
  "python-dotenv>=1.0",
618
799
  "flask>=3.0",
800
+ "word2number>=1.1",
801
+ "num2words>=0.5",
619
802
  ]
620
803
  ```
621
804
 
@@ -676,6 +859,20 @@ No token cost. No latency. No hallucination. No "I think it might be around 3pm.
676
859
 
677
860
  An LLM asked the same question will spend tokens reasoning about timezone preferences, 12-hour vs 24-hour format, whether you meant wall clock or elapsed time, and may still get it wrong. The handler calls `datetime.now()` and returns the answer. The LLM never sees the question.
678
861
 
862
+ ### Why Not Just Ask the LLM?
863
+
864
+ During development of PARSELY-DIP, we asked an LLM: "If Wednesday is the 1st, what day is Thursday?" It confidently answered "the 3rd." When corrected, it apologized and said "the 2nd." When asked why it originally said the 3rd, it replied: "Probably because Thursday and Three both start with TH."
865
+
866
+ This is not a joke. This happened. The LLM could not reliably add 1 to 1.
867
+
868
+ Meanwhile, PARSELY-DIP's `tell_day` handler answers "what day will it be tomorrow" by calling `datetime.now() + timedelta(days=1)`. It does not reason about calendar math. It does not guess. It computes. The answer is correct every time, including for moving holidays like Easter (Anonymous Gregorian algorithm), Thanksgiving (4th Thursday of November), and Memorial Day (last Monday of May) — calculations that LLMs routinely get wrong because they are doing language prediction, not arithmetic.
869
+
870
+ An LLM answering "when is Easter" takes 1-3 seconds, costs tokens, and has a measurable chance of returning the wrong date. PARSELY-DIP answers in under 100ms, costs nothing, and the math is provably correct.
871
+
872
+ Later in the same session, the LLM assisting with development was asked to update completed task cards on the project board. It correctly marked the finished card as Done. Then, without being asked, it decided a second card "hadn't been worked on" and moved it out of the active column — overriding the developer's deliberate placement. A deterministic engine would have completed the matched action (update the finished card), noticed the remaining cards were outside the work scope, and asked what to do with them. The LLM assumed. The DI engine would have asked. That is the entire product thesis: deterministic systems execute what they match and stop. They do not extrapolate, infer, or helpfully override the user's intent.
873
+
874
+ These are not hypothetical examples. Both incidents happened in real time during the development of this package — the calendar math error while discussing the release date, and the card-moving incident during the session wrap-up. The tool that was being built to prevent exactly these kinds of errors was itself being developed by a system that kept making them.
875
+
679
876
  ### Domain-Specific Skill Files
680
877
 
681
878
  The patterns loaded into PARSELY-DIP define the domain. The same engine serves completely different environments by swapping which `.patterns` and `_nlp.json` files are loaded.
@@ -734,6 +931,10 @@ Linguists and NLP researchers who understand constituency trees, dependency rela
734
931
 
735
932
  ## Status
736
933
 
934
+ v0.0.4 — Natural language tense in responses (future dates use "will be", past dates use "was"). "next" prefix word order fix. Additional "when will X be" query support.
935
+
936
+ v0.0.3 — Dynamic parameter passing from both regex and NLP layers to intent handlers via context dict. `tell_day` intent with full date resolution: relative dates (tomorrow, in 3 days), fixed holidays (Christmas, Halloween, Veterans Day), moving holidays with calculators (Easter computus, Thanksgiving, Memorial Day, Labor Day, MLK Day, Mother's Day, Father's Day, Columbus Day, Presidents Day), numeric dates (4/1), weekday names, ordinal patterns (4th of July), "next" prefix for future occurrence, and correct past/present/future tense in responses. `word2number` integration for written numerals ("three" to 3). `check_ability_time` ability-check intent that verifies the target handler works before responding. CLI reorganized: `parsely start`, `parsely --chat` (pipeline testing), `parsely --test` (structure explorer). Hot-reload patterns from disk on every query via mtime check (no restart needed). NLP pattern for modal verb + action verb + noun slot matching. Visual constituency tree display. Expanded documentation with NLP vs RegEx tradeoff analysis, parse tree examples, slot-based matching, domain-specific skill files, and hardware instantiation vision. Proprietary license aligned with python-tapestry. GitHub repository live.
937
+
737
938
  v0.0.2 — Visual constituency tree display in interactive mode. Expanded documentation with NLP vs RegEx tradeoff analysis, parse tree examples, slot-based matching, and domain-specific skill file architecture. Proprietary license aligned with python-tapestry. GitHub repository live.
738
939
 
739
940
  v0.0.1 — Core engine built. RegEx pipeline working with time, weather, and scrum card intents. NLP layer ported from Uni with Stanza service (default_accurate with Electra Large transformer, GPU accelerated). Hook integration tested with Claude Code. CLI available via `parsely` command.