parsely-dip 0.0.2__tar.gz → 0.0.3__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.3}/PKG-INFO +201 -6
  2. parsely_dip-0.0.2/src/parsely_dip.egg-info/PKG-INFO → parsely_dip-0.0.3/README.md +925 -753
  3. {parsely_dip-0.0.2 → parsely_dip-0.0.3}/pyproject.toml +3 -1
  4. {parsely_dip-0.0.2 → parsely_dip-0.0.3}/src/parsely_dip/__init__.py +20 -11
  5. parsely_dip-0.0.3/src/parsely_dip/cli/main.py +118 -0
  6. {parsely_dip-0.0.2 → parsely_dip-0.0.3}/src/parsely_dip/engine/nlp.py +8 -2
  7. {parsely_dip-0.0.2 → parsely_dip-0.0.3}/src/parsely_dip/engine/regex.py +12 -4
  8. {parsely_dip-0.0.2 → parsely_dip-0.0.3}/src/parsely_dip/engine/registry.py +14 -2
  9. {parsely_dip-0.0.2 → parsely_dip-0.0.3}/src/parsely_dip/engine/stanza_service.py +4 -1
  10. parsely_dip-0.0.3/src/parsely_dip/intents/day.py +364 -0
  11. parsely_dip-0.0.3/src/parsely_dip/intents/time.py +33 -0
  12. parsely_dip-0.0.2/README.md → parsely_dip-0.0.3/src/parsely_dip.egg-info/PKG-INFO +948 -732
  13. {parsely_dip-0.0.2 → parsely_dip-0.0.3}/src/parsely_dip.egg-info/SOURCES.txt +1 -0
  14. {parsely_dip-0.0.2 → parsely_dip-0.0.3}/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.3}/LICENSE +0 -0
  18. {parsely_dip-0.0.2 → parsely_dip-0.0.3}/setup.cfg +0 -0
  19. {parsely_dip-0.0.2 → parsely_dip-0.0.3}/src/parsely_dip/cli/__init__.py +0 -0
  20. {parsely_dip-0.0.2 → parsely_dip-0.0.3}/src/parsely_dip/engine/__init__.py +0 -0
  21. {parsely_dip-0.0.2 → parsely_dip-0.0.3}/src/parsely_dip/engine/splitter.py +0 -0
  22. {parsely_dip-0.0.2 → parsely_dip-0.0.3}/src/parsely_dip/intents/__init__.py +0 -0
  23. {parsely_dip-0.0.2 → parsely_dip-0.0.3}/src/parsely_dip/intents/scrum.py +0 -0
  24. {parsely_dip-0.0.2 → parsely_dip-0.0.3}/src/parsely_dip/intents/weather.py +0 -0
  25. {parsely_dip-0.0.2 → parsely_dip-0.0.3}/src/parsely_dip/patterns/__init__.py +0 -0
  26. {parsely_dip-0.0.2 → parsely_dip-0.0.3}/src/parsely_dip.egg-info/dependency_links.txt +0 -0
  27. {parsely_dip-0.0.2 → parsely_dip-0.0.3}/src/parsely_dip.egg-info/entry_points.txt +0 -0
  28. {parsely_dip-0.0.2 → parsely_dip-0.0.3}/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.3
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 is Monday, March 30, 2026.
459
+
460
+ >>> what day will it be in three days
461
+ in 3 days is Wednesday, April 01, 2026.
462
+
463
+ >>> what day is April Fools
464
+ April Fool's Day is Wednesday, April 01, 2026.
465
+
466
+ >>> what day is on 4/1
467
+ 4/1/2026 is Wednesday, April 01, 2026.
468
+
469
+ >>> when is easter
470
+ Easter is Sunday, April 05, 2026.
471
+
472
+ >>> when is thanksgiving
473
+ Thanksgiving is Thursday, November 26, 2026.
474
+
475
+ >>> when is the next 4th of July
476
+ Independence Day is Saturday, July 04, 2026.
477
+
478
+ >>> when is mothers day
479
+ Mother's Day is 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 is Friday, December 25, 2026.
486
+
487
+ >>> what day is memorial day
488
+ Memorial Day is Monday, May 25, 2026.
489
+
490
+ >>> what day is labor day
491
+ Labor Day is 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
509
646
 
510
- ```bash
511
- python -m parsely_dip.engine.stanza_service --chat
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.
659
+
660
+ ```
661
+ >>> could you please tell me the time
662
+ Yes, just ask 'what time is it?' or 'what's the time?'
663
+
664
+ >>> what time is it?
665
+ 06:12
666
+
667
+ >>> hello there
668
+ [No match — would fall through to LLM]
512
669
  ```
513
670
 
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.
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,16 @@ 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
+
679
872
  ### Domain-Specific Skill Files
680
873
 
681
874
  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 +927,8 @@ Linguists and NLP researchers who understand constituency trees, dependency rela
734
927
 
735
928
  ## Status
736
929
 
930
+ 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.
931
+
737
932
  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
933
 
739
934
  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.