Struct DocumentPlan 

pub struct DocumentPlan {
    pub paragraphs: Vec<Paragraph>,
}

A planned document — a structured narrative with paragraph breaks.

Use DocumentPlan::from_events to auto-organize events by salience and entity groupings, then .render(&engine) to produce the final narrative.

Fields

paragraphs: Vec<Paragraph>

Implementations

impl DocumentPlan

pub fn new() -> Self

pub fn from_events(events: &[(&str, Context)], engine: &Engine) -> Self

Build a document plan from a flat set of events, using the default entity-grouping strategy.

Organization:

1. Assign each event a salience (from context or explicit thresholds).
2. Group consecutive events that share an entity into the same paragraph.
3. Order paragraphs by highest-salience first.

Within a paragraph, events keep their original order (which the engine’s discourse state can then leverage for pronouns and connectives).

To group by action category instead, use DocumentPlan::from_events_grouped or DocumentPlan::from_events_classified.

pub fn from_events_grouped( events: &[(&str, Context)], engine: &Engine, strategy: GroupingStrategy, ) -> Self

Build a document plan with an explicit grouping strategy.

pub fn from_events_classified<F>( events: &[(&str, Context)], engine: &Engine, classifier: F, ) -> Self

where F: Fn(&str) -> RhetoricalCategory,

Build a GroupingStrategy::ByAction plan with a custom classifier. Useful when template keys don’t match the default classifier’s vocabulary (e.g., domain-specific verbs like "issue.closed").

pub fn from_events_with_relations( events: &[(&str, Context, Option<RstRelation>)], engine: &Engine, ) -> Self

Build a GroupingStrategy::ByEntity plan where each event carries an optional RST relation describing its rhetorical link to the preceding event within the same paragraph.

Events that start a new paragraph (different entity) have their relation silently dropped — relations are meaningful only within a paragraph, not across paragraph boundaries.

pub fn render_structured( &self, engine: &Engine, session: &mut Session, ) -> Result<RenderedDocument, ProsaicError>

Render the document plan into a narrative.

Paragraphs are separated by a double newline. Between paragraphs the paragraph-local discourse state is reset so pronouns don’t span paragraph boundaries, but narrative-level style rotation is preserved.

When any event in a paragraph carries an RST relation, the paragraph is rendered via Engine::render_batch_with_relations which inserts discourse markers (“Furthermore, “, “However, “, etc.) between events. Paragraphs whose relations are all None fall back to the standard Engine::render_batch path so aggregation still applies. Render this plan into a [RenderedDocument] — the structured intermediate consumed by retrospective-pass diagnosers and the composite scorer.

Behaviorally identical to Self::render for the flat text: render_structured(engine, session)?.text == render(engine, session)? holds when no inter-event gapping (forward conjunction reduction) applies inside any paragraph. When gapping does apply, this method produces sentence-by-sentence text without the gapped form, which is what diagnosers want — they reason at sentence granularity, not at the gapped-clause level. Callers that need the gapped flat string should keep using render.

pub fn render_refined( &self, engine: &Engine, session: &mut Session, ) -> Result<RefineOutcome, ProsaicError>

Run the retrospective refine loop over this plan. Equivalent to Self::render when the engine’s crate::RefineConfig is off, otherwise iterates with structural diagnosers per the loop spec. Always produces a complete output; faithfulness-failing iterations are silently rejected and the loop falls back to the previous best.

pub fn render( &self, engine: &Engine, session: &mut Session, ) -> Result<String, ProsaicError>

Trait Implementations

impl Clone for DocumentPlan

fn clone(&self) -> DocumentPlan

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DocumentPlan

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for DocumentPlan

fn default() -> Self

Returns the “default value” for a type.