Args:
    parsed_doc: Output from vision parser {"text", "method", "confidence"}
    calendar_events: List of upcoming calendar events for conflict detection
    family_members: List of family members this affects (auto-detected if None)
    urgency: "low", "medium", "high"

Returns:
    Structured briefing card with title, summary, details, conflicts, actions
"""
# Load family config for context
family_config = get_family_config()

# Auto-detect family members from document text if not provided
if family_members is None:
    text = parsed_doc.get("text", "")
    inferred = family_config.infer_recipients(text)
    if inferred:
        family_members = [m["member_id"] for m in inferred]
        # Add confidence metadata
        member_confidence = {m["member_id"]: m["confidence"] for m in inferred}
    else:
        family_members = ["Family"]
        member_confidence = {}
else:
    member_confidence = {}

# Determine model based on task complexity
model = get_model_for_task("complex")  # Uses 8B for briefing generation
validate_ollama_request(model)

# Prepare context
calendar_context = json.dumps(calendar_events or [], indent=2, default=str)
family_context = family_config.build_context_prompt()

prompt = BRIEFING_PROMPT.format(
    document_text=parsed_doc.get("text", "")[:4000],  # Limit context
    calendar_context=calendar_context[:1000],
    family_members=family_context
)

async with httpx.AsyncClient(timeout=120.0) as client:
    response = await client.post(
        f"{OLLAMA_BASE_URL}/api/chat",
        json={
            "model": model,
            "messages": [{"role": "user", "content": prompt}],
            "format": "json",
            "stream": False,
            "options": {
                "temperature": 0.3,  # Lower for consistent JSON
                "num_predict": 2048
            }
        }
    )
    response.raise_for_status()
    result = response.json()

# Parse JSON response
try:
    content = result.get("message", {}).get("content", "")
    # Handle markdown code blocks if present
    if "```json" in content:
        content = content.split("```json")[1].split("```")[0].strip()
    elif "```" in content:
        content = content.split("```")[1].split("```")[0].strip()

    briefing = json.loads(content)

    # Ensure required fields
    briefing.setdefault("title", "Briefing")
    briefing.setdefault("summary", parsed_doc.get("text", "")[:200] + "...")
    briefing.setdefault("key_details", {})
    briefing.setdefault("conflicts", [])
    briefing.setdefault("suggested_actions", [])
    briefing.setdefault("confidence", 0.5)
    briefing.setdefault("category", "info")

    # Add metadata
    briefing["_meta"] = {
        "model_used": model,
        "parser_method": parsed_doc.get("method", "unknown"),
        "generated_at": datetime.now().isoformat(),
        "urgency": urgency
    }

    # Determine if this briefing has calendar-applicable events
    # (events with detected dates/times that can be added to calendar)
    briefing["action_buttons"] = _detect_calendar_actions(briefing)

    # Classify event type and persist to Event Graph
    briefing["event_type"] = classify_event_type(briefing)
    try:
        doc_id = _generate_document_id(parsed_doc)
        EventGraphWriter().write(doc_id, briefing, briefing)
    except Exception as e:
        # Event Graph write failure is non-fatal — briefing still returned
        print(f"    [Event Graph] Write failed: {e}", file=sys.stderr)

    return briefing

except json.JSONDecodeError as e:
    # Fallback if JSON parsing fails
    return {
        "title": "Document Summary",
        "summary": parsed_doc.get("text", "")[:300] + "...",
        "key_details": {},
        "conflicts": [],
        "suggested_actions": ["Review document manually"],
        "confidence": 0.3,
        "category": "info",
        "action_buttons": {"has_calendar_event": False, "can_add_to_calendar": False},
        "_meta": {
            "model_used": model,
            "parser_method": parsed_doc.get("method", "unknown"),
            "error": f"JSON parse failed: {e}",
            "generated_at": datetime.now().isoformat()
        }
    }

prompt = f"Summarize this in {max_words} words or less:\n\n{text[:2000]}"

async with httpx.AsyncClient(timeout=30.0) as client:
    response = await client.post(
        f"{OLLAMA_BASE_URL}/api/chat",
        json={
            "model": model,
            "messages": [{"role": "user", "content": prompt}],
            "stream": False
        }
    )
    response.raise_for_status()
    result = response.json()
    return result.get("message", {}).get("content", "")[:500]

Returns a dict with:
  has_calendar_event: bool — whether the briefing contains date/time info
  can_add_to_calendar: bool — whether we have enough info to create a calendar event
  event_summary: str — the event title for the button
  event_start: str — ISO datetime string if available
  event_end: str — ISO datetime string if available
  event_location: str — location if available
  category: str — briefing category (event, appointment, deadline, info, urgent)

Calendar buttons are shown for briefings that:
- Have detected dates/times in key_details
- Are categorized as event, appointment, or deadline
- Are NOT pure info (no actionable date/time)
"""
category = briefing.get("category", "info")
key_details = briefing.get("key_details", {})
if not isinstance(key_details, dict):
    key_details = {}

# Check for date/time fields
date_val = key_details.get("date", "") or key_details.get("Date", "")
time_val = key_details.get("time", "") or key_details.get("Time", "")
location = key_details.get("location", "") or key_details.get("Location", "")
start_time = key_details.get("start", "") or key_details.get("Start", "")
end_time = key_details.get("end", "") or key_details.get("End", "")

# Try to construct start/end from date + time fields
event_start = start_time or ""
event_end = end_time or ""

if date_val and time_val:
    # Combine date and time: "2026-05-03" + "2:00 PM" → "2026-05-03 2:00 PM"
    event_start = f"{date_val} {time_val}" if not start_time else start_time
elif date_val and not event_start:
    event_start = date_val

# Determine if this is calendar-applicable
has_date = bool(date_val or event_start)
calendar_categories = {"event", "appointment", "deadline", "urgent"}
is_calendar_category = category in calendar_categories

# Info-only documents without dates don't get calendar buttons
has_calendar_event = has_date and is_calendar_category
can_add_to_calendar = has_calendar_event and bool(briefing.get("title"))

return {
    "has_calendar_event": has_calendar_event,
    "can_add_to_calendar": can_add_to_calendar,
    "event_summary": briefing.get("title", "Event"),
    "event_start": event_start,
    "event_end": event_end,
    "event_location": location if isinstance(location, str) else str(location),
    "category": category,
}

Uses filename hash if available, or text hash as fallback.

Args:
    parsed_doc: Parsed document with "text", optional "filename" metadata

Returns:
    Stable string identifier for the document
"""
import hashlib

# Try to get filename from metadata
meta = parsed_doc.get("_meta", {})
if isinstance(meta, dict):
    filename = meta.get("source_filename") or meta.get("filename")
else:
    filename = None

if not filename:
    # Fallback to text hash
    text = parsed_doc.get("text", "")
    content_hash = hashlib.sha256(text.encode()).hexdigest()[:16]
    return f"text_{content_hash}"

# Generate from filename
safe_name = "".join(c if c.isalnum() else "_" for c in filename[:32])
text = parsed_doc.get("text", "")
content_hash = hashlib.sha256(text.encode()).hexdigest()[:12]
return f"{safe_name}_{content_hash}"