ldr/redmine
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9ee9eb3ec69d5a17db3d74c4b29c9f873ab56727
redmine/redmine_ticket_nmi.py
T
Jason Thistlethwaite 9ee9eb3ec6 Organized
2026-10-17 20:50:35 -04:00

629 lines
21 KiB
Python
Raw Blame History

#!/usr/bin/env python3
"""Bridge Redmine ticket entities → NMI agent CLI (mrscClient-php bin/nmi).
Pattern extract stays in redmine_ticket_entities.py (no NMI I/O).
This module shells out to the NMI CLI for resolve / cs-brief using those hints.
"""
from __future__ import annotations
import json
import os
import re
import shutil
import subprocess
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any, Iterable, Optional
# Prefer env overrides for agents/profiles
DEFAULT_NMI_BIN = os.environ.get(
"NMI_CLI",
"/home/jason/projects/mrscClient-php/bin/nmi",
)
DEFAULT_ENV_FILE = os.environ.get(
"NMI_ENV_FILE",
"/home/jason/projects/mrscClient-php/examples/modern/.env",
)
DEFAULT_MODE = os.environ.get("NMI_MODE", "dev")
# Entity types that map cleanly into NMI resolve ids
_TRACKING_TYPES = {
"tracking_ups",
"tracking_usps",
"tracking_fedex_candidate",
}
_ORDER_TYPES = {"order_amazon", "order_id"}
_ITEM_TYPES = {"item_no", "item_or_sku"}
_ACCOUNT_TYPES = {"account_ref"}
# NMI deep link templates (from obsidian-ldr/INBOX/WIP/Linking to Entities Within NMI.md)
NMI_BASE = "https://app.ldrprep.com"
NMI_LINKS = {
"item_no": {
"manager": lambda v: f"{NMI_BASE}/?page=itemManager&itemNo={v}",
"statement": lambda v: f"{NMI_BASE}/?page=itemStatement&itemNo={v}",
},
"item_or_sku": {
"manager": lambda v: f"{NMI_BASE}/?page=itemManager&itemNo={v}",
},
"tracking_ups": {"box_history": lambda v: f"{NMI_BASE}/?page=boxFinder&tracking_number={v}&action=search"},
"tracking_usps": {"box_history": lambda v: f"{NMI_BASE}/?page=boxFinder&tracking_number={v}&action=search"},
"tracking_fedex_candidate": {"box_history": lambda v: f"{NMI_BASE}/?page=boxFinder&tracking_number={v}&action=search"},
"order_id": {"order_summary": lambda v: f"{NMI_BASE}/?page=requests&filter=view&id={v}"},
"request_id": {"package_history": lambda v: f"{NMI_BASE}/?page=boxFinder&request_id={v}"},
"account_ref": {"user_info": lambda v: f"{NMI_BASE}/?page=userInfo&accountNo={v}"},
}
# LDR unit item numbers commonly 9 digits starting with 2
_ITEM_NO_BARE = re.compile(r"\b(2\d{8})\b")
@dataclass(frozen=True)
class NmiRuntimeProfile:
"""Resolved NMI execution settings plus a preflight result."""
mode: str
env_file: Path
nmi_bin: Path
endpoint: Optional[str]
ready: bool
problem: Optional[str] = None
def resolve_runtime_profile(
*,
mode: Optional[str] = None,
env_file: Optional[str] = None,
nmi_bin: Optional[str] = None,
endpoint: Optional[str] = None,
environ: Optional[dict[str, str]] = None,
) -> NmiRuntimeProfile:
"""Resolve the exact profile passed to PHP before an NMI subprocess starts.
An env file that is empty or missing is always rejected. It is too easy for
the checked-in example `.env` to otherwise select a surprising dev/default
path while making the TUI look successful.
"""
env = os.environ if environ is None else environ
requested_mode = (mode or env.get("NMI_MODE") or DEFAULT_MODE).strip().lower()
normalized_mode = "production" if requested_mode in {"prod", "production"} else requested_mode
selected_env_file = Path(env_file or env.get("NMI_ENV_FILE") or DEFAULT_ENV_FILE).expanduser()
selected_nmi_bin = Path(nmi_bin or env.get("NMI_CLI") or DEFAULT_NMI_BIN).expanduser()
mode_upper = normalized_mode.upper()
selected_endpoint = (
endpoint
or env.get(f"NMI_ENDPOINT_{mode_upper}")
or env.get("NMI_ENDPOINT")
or None
)
if not selected_env_file.is_file():
return NmiRuntimeProfile(
mode=normalized_mode,
env_file=selected_env_file,
nmi_bin=selected_nmi_bin,
endpoint=selected_endpoint,
ready=False,
problem=f"NMI env file does not exist: {selected_env_file}",
)
if selected_env_file.stat().st_size == 0:
return NmiRuntimeProfile(
mode=normalized_mode,
env_file=selected_env_file,
nmi_bin=selected_nmi_bin,
endpoint=selected_endpoint,
ready=False,
problem=f"NMI env file is empty: {selected_env_file}",
)
if not selected_nmi_bin.is_file():
return NmiRuntimeProfile(
mode=normalized_mode,
env_file=selected_env_file,
nmi_bin=selected_nmi_bin,
endpoint=selected_endpoint,
ready=False,
problem=f"NMI CLI does not exist: {selected_nmi_bin}",
)
return NmiRuntimeProfile(
mode=normalized_mode,
env_file=selected_env_file,
nmi_bin=selected_nmi_bin,
endpoint=selected_endpoint,
ready=True,
)
@dataclass
class NmiLookupPlan:
"""Deduped identifiers to try against NMI, highest confidence first."""
tracking: list[str] = field(default_factory=list)
order_id: list[str] = field(default_factory=list)
item_no: list[str] = field(default_factory=list)
account: list[str] = field(default_factory=list)
skipped: list[dict[str, str]] = field(default_factory=list)
def is_empty(self) -> bool:
return not (self.tracking or self.order_id or self.item_no or self.account)
def enrich_entities_with_item_nos(
entities: list[dict[str, str]], text: str
) -> list[dict[str, str]]:
"""Add bare LDR-style item numbers when not already present."""
seen = {(e.get("type"), (e.get("value") or "").upper()) for e in entities}
out = list(entities)
for m in _ITEM_NO_BARE.finditer(text or ""):
val = m.group(1)
key = ("item_no", val)
if key in seen:
continue
# Avoid treating pure tracking-ish long numbers: item is exactly 9 digits
out.append({"type": "item_no", "value": val, "confidence": "medium"})
seen.add(key)
return out
def plan_from_entities(entities: Iterable[dict[str, str]]) -> NmiLookupPlan:
plan = NmiLookupPlan()
seen_t: set[str] = set()
seen_o: set[str] = set()
seen_i: set[str] = set()
seen_a: set[str] = set()
# Sort high confidence first
ordered = sorted(
entities,
key=lambda e: {"high": 0, "medium": 1, "low": 2}.get(e.get("confidence") or "high", 3),
)
for e in ordered:
kind = e.get("type") or ""
val = (e.get("value") or "").strip()
conf = e.get("confidence") or "high"
if not val:
continue
if kind in _TRACKING_TYPES:
if conf == "low" and kind == "tracking_fedex_candidate":
plan.skipped.append(e)
continue
u = val.upper()
if u not in seen_t:
seen_t.add(u)
plan.tracking.append(val)
elif kind in _ORDER_TYPES:
if val not in seen_o:
seen_o.add(val)
plan.order_id.append(val)
elif kind in _ITEM_TYPES or kind == "item_no":
# Prefer pure numeric item_no; SKU-like may still help as order/item search later
if re.fullmatch(r"\d{6,12}", val):
if val not in seen_i:
seen_i.add(val)
plan.item_no.append(val)
else:
plan.skipped.append({**e, "reason": "sku_not_numeric_item"})
elif kind in _ACCOUNT_TYPES:
if val not in seen_a:
seen_a.add(val)
plan.account.append(val)
else:
plan.skipped.append(e)
return plan
def _php_bin() -> str:
return shutil.which("php") or "php"
def run_nmi(
args: list[str],
*,
mode: str = DEFAULT_MODE,
env_file: str = DEFAULT_ENV_FILE,
nmi_bin: str = DEFAULT_NMI_BIN,
endpoint: Optional[str] = None,
timeout: int = 60,
) -> subprocess.CompletedProcess[str]:
cmd = [_php_bin(), nmi_bin, *args, f"--mode={mode}", f"--env-file={env_file}"]
if endpoint:
cmd.append(f"--endpoint={endpoint}")
return subprocess.run(
cmd,
capture_output=True,
text=True,
timeout=timeout,
check=False,
)
def try_resolve_ids(
plan: NmiLookupPlan,
*,
mode: str = DEFAULT_MODE,
env_file: str = DEFAULT_ENV_FILE,
nmi_bin: str = DEFAULT_NMI_BIN,
endpoint: Optional[str] = None,
include_pictures: bool = False,
max_attempts: int = 6,
) -> dict[str, Any]:
"""Try NMI resolve with identifiers from the plan until one succeeds."""
attempts: list[dict[str, Any]] = []
candidates: list[list[str]] = []
for item in plan.item_no:
candidates.append(["resolve", f"--item-no={item}"])
for tn in plan.tracking:
candidates.append(["resolve", f"--tracking={tn}"])
for oid in plan.order_id:
candidates.append(["resolve", f"--order-id={oid}"])
for acct in plan.account:
candidates.append(["resolve", f"--account={acct}"])
if include_pictures:
for c in candidates:
c.append("--pictures")
for args in candidates[:max_attempts]:
proc = run_nmi(args, mode=mode, env_file=env_file, nmi_bin=nmi_bin, endpoint=endpoint)
attempt = {
"args": args,
"returncode": proc.returncode,
"stderr": (proc.stderr or "").strip()[:500],
}
if proc.returncode == 0 and (proc.stdout or "").strip():
try:
data = json.loads(proc.stdout)
except json.JSONDecodeError as exc:
attempt["error"] = f"json_decode: {exc}"
attempts.append(attempt)
continue
attempt["ok"] = True
attempts.append(attempt)
return {"ok": True, "result": data, "attempts": attempts, "used_args": args}
attempt["ok"] = False
attempts.append(attempt)
return {"ok": False, "result": None, "attempts": attempts, "used_args": None}
def try_cs_brief(
plan: NmiLookupPlan,
*,
mode: str = DEFAULT_MODE,
env_file: str = DEFAULT_ENV_FILE,
nmi_bin: str = DEFAULT_NMI_BIN,
endpoint: Optional[str] = None,
max_attempts: int = 6,
) -> dict[str, Any]:
"""Try cs-brief with plan identifiers until one returns text."""
attempts: list[dict[str, Any]] = []
candidates: list[list[str]] = []
for item in plan.item_no:
candidates.append(["cs-brief", f"--item-no={item}"])
for tn in plan.tracking:
candidates.append(["cs-brief", f"--tracking={tn}"])
for oid in plan.order_id:
candidates.append(["cs-brief", f"--order-id={oid}"])
for acct in plan.account:
candidates.append(["cs-brief", f"--account={acct}"])
for args in candidates[:max_attempts]:
proc = run_nmi(args, mode=mode, env_file=env_file, nmi_bin=nmi_bin, endpoint=endpoint)
attempt = {
"args": args,
"returncode": proc.returncode,
"stderr": (proc.stderr or "").strip()[:500],
}
text = (proc.stdout or "").strip()
if proc.returncode == 0 and text and "=== NMI CS BRIEF ===" in text:
attempt["ok"] = True
attempts.append(attempt)
return {"ok": True, "text": text + ("\n" if not text.endswith("\n") else ""), "attempts": attempts, "used_args": args}
attempt["ok"] = False
if text:
attempt["stdout_preview"] = text[:200]
attempts.append(attempt)
return {"ok": False, "text": None, "attempts": attempts, "used_args": None}
def brief_for_issue(
issue: dict[str, Any],
entities: list[dict[str, str]],
*,
mode: str = DEFAULT_MODE,
env_file: str = DEFAULT_ENV_FILE,
nmi_bin: str = DEFAULT_NMI_BIN,
endpoint: Optional[str] = None,
with_history: bool = True,
) -> dict[str, Any]:
profile = resolve_runtime_profile(
mode=mode,
env_file=env_file,
nmi_bin=nmi_bin,
endpoint=endpoint,
)
runtime = {
"mode": profile.mode,
"env_file": str(profile.env_file),
"nmi_bin": str(profile.nmi_bin),
"endpoint": profile.endpoint,
"ready": profile.ready,
"problem": profile.problem,
}
# Prefer public extract path text rebuild without private imports
try:
from redmine_ticket_entities import extract_entities_from_issue as _ex
# rebuild text via extract side-channel: re-run extract on issue already given
# Use journals/subject from issue for bare item_no enrichment only
chunks = []
for key in ("subject", "description"):
if issue.get(key):
chunks.append(str(issue[key]))
journals = issue.get("journals")
if isinstance(journals, list):
for j in journals[-15:]:
if isinstance(j, dict) and j.get("notes"):
chunks.append(str(j["notes"]))
text = "\n".join(chunks)
_ = _ex # silence unused if tree-shaken
except Exception:
text = str(issue.get("subject") or "") + "\n" + str(issue.get("description") or "")
ents = enrich_entities_with_item_nos(entities, text)
plan = plan_from_entities(ents)
out: dict[str, Any] = {
"issue_id": issue.get("id"),
"runtime": runtime,
"plan": {
"tracking": plan.tracking,
"order_id": plan.order_id,
"item_no": plan.item_no,
"account": plan.account,
"skipped": plan.skipped,
},
"entities": ents,
}
if not profile.ready:
out["ok"] = False
out["error"] = "nmi_runtime_not_ready"
return out
if plan.is_empty():
out["ok"] = False
out["error"] = "no_nmi_candidates"
return out
brief = try_cs_brief(plan, mode=mode, env_file=env_file, nmi_bin=nmi_bin, endpoint=endpoint)
out["brief"] = brief
out["ok"] = bool(brief.get("ok"))
if not out["ok"]:
# still try resolve for structured debug
out["resolve"] = try_resolve_ids(
plan, mode=mode, env_file=env_file, nmi_bin=nmi_bin, endpoint=endpoint
)
out["error"] = "nmi_lookup_failed"
# Pull item history (new getItemHistory) when requested and item_no present
if with_history:
out = enrich_with_history(out, mode=mode, env_file=env_file, nmi_bin=nmi_bin, endpoint=endpoint)
return out
def format_private_note(payload: dict[str, Any]) -> str:
"""Build a Redmine private note body from nmi brief result.
Enhanced with:
- Deep NMI links (Item Manager, Box History, Request pages etc.) per the WIP note
- Item history from the new getItemHistory endpoint (billings, who moved, condition changes)
"""
lines = [
"=== Auto NMI pre-fetch (agent) ===",
f"issue_id: {payload.get('issue_id')}",
]
plan = payload.get("plan") or {}
lines.append(
"candidates: "
+ json.dumps(
{
"tracking": plan.get("tracking"),
"order_id": plan.get("order_id"),
"item_no": plan.get("item_no"),
"account": plan.get("account"),
},
sort_keys=True,
)
)
# Deep links from the WIP note
ents = payload.get("entities") or []
links = generate_nmi_links(ents)
if links:
lines.append("")
lines.append("=== NMI Deep Links (Item Manager / Box History / Request pages / userInfo) ===")
lines.extend(links[:12])
brief = payload.get("brief") or {}
if brief.get("ok") and brief.get("text"):
lines.append("")
lines.append(brief["text"].rstrip())
else:
lines.append("")
lines.append("NMI lookup did not resolve cleanly.")
if payload.get("error"):
lines.append(f"error: {payload['error']}")
attempts = brief.get("attempts") or (payload.get("resolve") or {}).get("attempts") or []
for a in attempts[:5]:
lines.append(f"- attempt {a.get('args')}: rc={a.get('returncode')} err={a.get('stderr') or a.get('error')}")
# New history
hist = payload.get("item_history") or {}
if hist.get("ok"):
lines.append("")
lines.append("=== Item History (getItemHistory) ===")
h = hist.get("history") or {}
if isinstance(h, dict) and h:
lines.append(json.dumps(h, indent=2, default=str)[:1600])
elif hist.get("text"):
lines.append(hist["text"][:1400])
else:
lines.append("(see raw for full history)")
elif "item_history" in payload:
lines.append("")
lines.append("Item history note: " + str((payload.get("item_history") or {}).get("error", "no data")))
lines.append("")
lines.append("_Generated by redmine_ticket_nmi; verify before customer-facing use._")
return "\n".join(lines) + "\n"
def generate_nmi_links(entities: list[dict[str, str]]) -> list[str]:
"""Produce a list of useful deep links based on resolved entities."""
links = []
seen = set()
for e in entities:
kind = e.get("type")
val = e.get("value")
if not kind or not val:
continue
templates = NMI_LINKS.get(kind, {})
for label, tmpl in templates.items():
url = tmpl(val)
key = (kind, val, label)
if key in seen:
continue
seen.add(key)
links.append(f"- {label} for {kind} {val}: {url}")
return links
def try_item_history(
item_no: str,
*,
mode: str = DEFAULT_MODE,
env_file: str = DEFAULT_ENV_FILE,
nmi_bin: str = DEFAULT_NMI_BIN,
endpoint: Optional[str] = None,
limit: int = 50,
snapshot: bool = True,
) -> dict[str, Any]:
"""Call nmi item history for a single item_no. Returns structured result."""
cmd = [
"php",
nmi_bin,
"item",
"history",
f"--item-no={item_no}",
f"--limit={limit}",
]
if snapshot:
cmd.append("--snapshot")
if mode:
cmd.extend(["--mode", mode])
if env_file:
cmd.extend(["--env-file", env_file])
if endpoint:
cmd.extend(["--endpoint", endpoint])
try:
res = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
if res.returncode != 0:
return {"ok": False, "error": res.stderr.strip() or res.stdout.strip(), "cmd": cmd}
# Try JSON first
try:
data = json.loads(res.stdout)
return {"ok": True, "history": data, "raw": res.stdout}
except Exception:
return {"ok": True, "text": res.stdout.strip(), "raw": res.stdout}
except Exception as exc:
return {"ok": False, "error": str(exc)}
def enrich_with_history(
payload: dict[str, Any],
*,
mode: str = DEFAULT_MODE,
env_file: str = DEFAULT_ENV_FILE,
nmi_bin: str = DEFAULT_NMI_BIN,
endpoint: Optional[str] = None,
) -> dict[str, Any]:
"""If an item_no is present in the plan, fetch its history and attach."""
plan = payload.get("plan") or {}
item_no = plan.get("item_no")
if not item_no:
return payload
hist = try_item_history(
str(item_no),
mode=mode,
env_file=env_file,
nmi_bin=nmi_bin,
endpoint=endpoint,
limit=60,
snapshot=True,
)
payload["item_history"] = hist
return payload
def try_auto_link_redmine_contact(
*,
contact_id: int,
tracking: list[str] | None = None,
order_id: list[str] | None = None,
item_no: list[str] | None = None,
mode: str = DEFAULT_MODE,
env_file: str = DEFAULT_ENV_FILE,
nmi_bin: str = DEFAULT_NMI_BIN,
) -> dict[str, Any]:
"""If we have a Redmine contact_id and identifiers from a ticket, try to resolve in NMI
and automatically create the redmine_contact_links entry.
This implements the pattern: ticket mentions tracking/order/item -> successful
cs-info/resolve -> the returned customer owns the shipment -> link the Redmine
contact to that NMI user_account using the new junction table.
"""
if not contact_id:
return {"ok": False, "reason": "no_contact_id"}
ids: list[str] = []
if tracking:
for t in tracking:
ids.extend(["--tracking", str(t)])
if order_id:
for o in order_id:
ids.extend(["--order-id", str(o)])
if item_no:
for i in item_no:
ids.extend(["--item-no", str(i)])
if not ids:
return {"ok": False, "reason": "no_identifiers"}
cmd = [nmi_bin, "link-contact", "--redmine-contact-id", str(contact_id), "--mode", mode]
if env_file and env_file != DEFAULT_ENV_FILE:
cmd.extend(["--env-file", env_file])
cmd.extend(ids)
try:
proc = subprocess.run(cmd, capture_output=True, text=True, timeout=90)
ok = proc.returncode == 0
result = {
"ok": ok,
"contact_id": contact_id,
"cmd": " ".join(cmd),
"stdout": (proc.stdout or "")[:2500],
"stderr": (proc.stderr or "")[:800],
}
if ok and proc.stdout:
try:
if proc.stdout.strip().startswith("{"):
result["parsed"] = json.loads(proc.stdout)
except Exception:
pass
return result
except Exception as e:
return {"ok": False, "contact_id": contact_id, "error": str(e)}
Reference in New Issue View Git Blame Copy Permalink