feat: schema builder DSL and memory policy developer experience

[shawkatkabbara]

Summary

• Adds new papr_memory.lib module — a decorator-based DSL for defining graph schemas, constraints, and memory policies with full IDE support
• Introduces Auto("prompt") for per-field LLM extraction guidance, e.g. Auto("Summarize the incident in 1-2 sentences") serializes to {"mode": "auto", "prompt": "..."}
• Updates README with comprehensive Graph Schemas & Memory Policies documentation

New Module: papr_memory.lib

File	Purpose
_properties.py	Auto, prop(), exact(), semantic(), fuzzy(), PropertyRef, edge()
_schema.py	@schema, @node, @lookup, @upsert, @resolve, @constraint decorators
_builders.py	build_schema_params(), build_link_to(), build_memory_policy(), serialize_set_values()
_conditions.py	And(), Or(), Not() conditional operators for when clauses

Auto("prompt") Example

from papr_memory.lib import And, Or, Not, Auto

@node
@upsert
@constraint(
    when=And(
        Or({"severity": "high"}, {"severity": "critical"}),
        Not({"status": "resolved"}),
    ),
    set={
        "flagged": True,
        "summary": Auto("Summarize the security incident in 1-2 sentences"),
    },
)
class Alert:
    alert_id: str = prop(search=exact())
    title: str = prop(required=True, search=semantic(0.85))
    severity: str = prop()
    status: str = prop()
    flagged: bool = prop()
    summary: str = prop()

Auto() (no args) continues to work as before — Auto("prompt") is additive.

Dependencies

• Backend PR: Papr-ai/memory — adds prompt field to PropertyValue model and injects extraction guidance into the LLM structured output schema
• This SDK PR should be merged after the backend PR lands

Test plan

• Auto().to_dict() → {"mode": "auto"} (backwards compatible)
• Auto("Summarize briefly").to_dict() → {"mode": "auto", "prompt": "Summarize briefly"}
• serialize_set_values({"summary": Auto("prompt")}) includes prompt in output
• @constraint(set={"summary": Auto("prompt")}) → build_schema_params() round-trips correctly
• All 104 tests pass across test_properties, test_builders, test_conditions, test_schema_decorators, test_integration

🤖 Generated with Claude Code

[amirkabbara]

Nice! Can we use a similar summary prompt template for auto as I have for messages with short med and long term summaries? Also this updates the existing summary so reads summary, sees new memory and updates summary if needed right?

Should we allow them to choose when to summarize (ie daily, after x memories, etc)

[amirkabbara]

see comment in conversation

[shawkatkabbara]

Great questions! Here's the breakdown:

Summary prompt templates

Yes! Auto("prompt") is exactly this. Devs can pass the same kind of prompt templates we use in the messages service (short/med/long term summaries) as per-field extraction guidance. e.g.:

@constraint(set={
    "short_summary": Auto("Summarize this batch in 2-3 sentences focusing on key decisions and progress"),
    "long_summary": Auto("Full session summary: main arc, overall progress, key outcomes in 5-7 sentences"),
})

The prompts get injected into the LLM's structured output schema as EXTRACTION GUIDANCE: <prompt> on each property description.

Updates existing summary — already supported via text_mode

The backend already has 3 modes (implemented and tested in node_constraint_resolver.py):

Mode	Wire Format	Behavior
replace (default)	{"mode": "auto"}	Overwrites existing value
append	{"mode": "auto", "text_mode": "append"}	Adds to end of existing text
merge	{"mode": "auto", "text_mode": "merge"}	LLM reads existing + new, combines intelligently

So for an evolving summary that reads existing and updates:

"summary": {"mode": "auto", "text_mode": "merge", "prompt": "Update the summary incorporating new information"}

The LLM sees the existing summary + new memory content and produces a merged result.

When to summarize (daily, after x memories)

Designed but not yet built. The enrich feature in our docs (ENRICH_AND_CONTEXT_DESIGN.md) has EnrichTrigger with on_create, on_update, on_access, scheduled, and manual triggers, plus max_age for staleness-based re-enrichment (e.g. "P7D" = every 7 days). Good candidate for a follow-up PR to pair with Auto("prompt").

Clarification: this PR does NOT add summary by default to all nodes

To be clear — this PR gives developers the tool to define per-field extraction prompts on their own schema constraints. It does not automatically add a summary property to every node type. The developer has to explicitly opt in by defining summary as a property on their node and using Auto("prompt") in a @constraint(set={...}). No default behavior changes for existing schemas.