# How Seed Generation in Ouroboros Creates Immutable Specifications from Interview Data

> Learn how Ouroboros seed generation transforms interview data into immutable specifications using LLMs and Pydantic models for robust requirement capture.

- Repository: [Q00/ouroboros](https://github.com/Q00/ouroboros)
- Tags: internals
- Published: 2026-03-14

---

**Seed generation in Ouroboros converts BigBang interview transcripts into immutable specifications by enforcing an ambiguity threshold of 0.2, extracting structured requirements via LLM with the `seed-architect` prompt, and encapsulating them in a frozen Pydantic model that prevents any post-creation mutation.**

The Q00/ouroboros repository implements a rigorous pipeline that transforms conversational requirements gathering into concrete, versioned artifacts. This process, known as **Seed generation**, ensures that only sufficiently clarified interview data becomes immutable specification objects that drive the entire workflow orchestration.

## The Five-Phase Seed Generation Pipeline

The transformation from free-form interview to read-only specification follows a strict sequence implemented in [`src/ouroboros/bigbang/seed_generator.py`](https://github.com/Q00/ouroboros/blob/main/src/ouroboros/bigbang/seed_generator.py).

### Phase 1: Ambiguity Gating

Before any extraction occurs, the system validates the clarity of the interview data. The `SeedGenerator.generate` method (lines [150‑166](https://github.com/Q00/ouroboros/blob/main/src/ouroboros/bigbang/seed_generator.py#L150-L166)) checks the `AmbiguityScore` against the constant `AMBIGUITY_THRESHOLD` defined in [`bigbang/ambiguity.py`](https://github.com/Q00/ouroboros/blob/main/bigbang/ambiguity.py).

Only interviews with an overall ambiguity score **≤ 0.2** proceed to seed creation. This gate guarantees that vague or contradictory requirements cannot become immutable specifications, preventing technical debt from entering the workflow at the specification level.

### Phase 2: Structured Extraction via LLM

Once ambiguity is cleared, the transcript undergoes structured extraction. The `_build_interview_context` method (lines [303‑322](https://github.com/Q00/ouroboros/blob/main/src/ouroboros/bigbang/seed_generator.py#L303-L322)) renders the conversation into a single context string.

This context is sent to the LLM with the strict `seed-architect` system prompt, which mandates an exact plain-text format covering goals, constraints, and ontology. The response is sanitized via `_preprocess_response` and parsed by `_parse_extraction_response` (lines [504‑534](https://github.com/Q00/ouroboros/blob/main/src/ouroboros/bigbang/seed_generator.py#L504-L534)) into a dictionary of requirement fields.

### Phase 3: Metadata Provenance

Every seed carries an audit trail. During generation, the code constructs a `SeedMetadata` instance (lines [191‑199](https://github.com/Q00/ouroboros/blob/main/src/ouroboros/bigbang/seed_generator.py#L191-L199)) that records:

- A unique UUID for the seed
- Creation timestamp
- Source interview ID
- The ambiguity score at creation time
- Parent seed link (for evolved specifications)

This metadata creates an immutable provenance chain linking the specification back to the exact conversation that produced it.

### Phase 4: Immutable Model Construction

The parsed requirements are transformed into the concrete Pydantic model `Seed` defined in [`src/ouroboros/core/seed.py`](https://github.com/Q00/ouroboros/blob/main/src/ouroboros/core/seed.py) (lines [55‑78](https://github.com/Q00/ouroboros/blob/main/src/ouroboros/core/seed.py#L55-L78)). All fields are declared with `frozen=True`, making the instance truly immutable—any attempt to modify an attribute raises a `ValidationError`.

The `_build_seed` method (lines [489‑558](https://github.com/Q00/ouroboros/blob/main/src/ouroboros/bigbang/seed_generator.py#L489-L558)) assembles the model with two distinct sections:

- **Immutable direction**: Goal, constraints, and acceptance criteria that can never change
- **Evolvable ontology**: Structured domain knowledge that may only be refined through the reflection step

### Phase 5: Persistent Storage

The finished `Seed` is serialized to YAML via `save_seed` (lines [691‑756](https://github.com/Q00/ouroboros/blob/main/src/ouroboros/bigbang/seed_generator.py#L691-L756)), preserving the full immutable specification for the execution engine. The `load_seed` method enables retrieval of these specifications for replay or audit purposes.

## Why Immutability Matters for Workflow Integrity

Immutability serves three critical functions in the Ouroboros architecture:

- **Consistency across generations**: Once stored, the orchestrator can replay any generation without risking specification drift or mutation side effects.
- **Auditability**: The combination of `Seed` data and `SeedMetadata` forms a complete provenance record, enabling forensic analysis of why a particular workflow path was taken.
- **Safety**: By freezing the "direction" component (goals, constraints, acceptance criteria), the system prevents accidental changes that could violate the original business requirements during long-running workflows.

## Handling Evolution in Generation 2 and Beyond

When workflows proceed to later generations, the `generate_from_reflect` method (lines [178‑210](https://github.com/Q00/ouroboros/blob/main/src/ouroboros/bigbang/seed_generator.py#L178-L210)) creates new seeds while preserving immutability guarantees.

This method mutates only the **ontology** section based on reflection insights, copying the parent's immutable direction fields unchanged. It establishes a strict lineage by setting the `parent_seed_id` in the new seed's metadata, creating an auditable chain of specification evolution without ever altering historical artifacts.

## Practical Implementation Example

The following example demonstrates the complete flow from interview to immutable seed:

```python

# ----------------------------------------------------------------------

# Example: generate a Seed from a completed interview

# ----------------------------------------------------------------------

from pathlib import Path
from ouroboros.bigbang.seed_generator import SeedGenerator
from ouroboros.bigbang.interview import InterviewEngine, InterviewState
from ouroboros.bigbang.ambiguity import AmbiguityScore
from ouroboros.providers.litellm_adapter import LiteLLMAdapter  # any LLMAdapter implementation

# 1️⃣  Run the interview (this would normally be interactive)

engine = InterviewEngine()
state: InterviewState = await engine.start_interview(
    initial_context="Build a CLI task manager"
)

# 2️⃣  Compute ambiguity (the engine already does this)

ambiguity: AmbiguityScore = await engine.compute_ambiguity(state)

# 3️⃣  Create the seed generator with an LLM adapter

generator = SeedGenerator(llm_adapter=LiteLLMAdapter())

# 4️⃣  Generate the immutable Seed (throws ValidationError if ambiguity > 0.2)

result = await generator.generate(state=state, ambiguity_score=ambiguity)

if result.is_ok:
    seed = result.value
    print("✅ Seed created – ID:", seed.metadata.seed_id)
    # 5️⃣  Persist to YAML (optional)

    await generator.save_seed(seed, Path("my_seed.yaml"))
else:
    print("❌ Seed generation failed:", result.error)

```

This implementation follows the exact control flow defined in `SeedGenerator.generate` and `SeedGenerator._build_seed`, ensuring the resulting artifact is immutable and ready for workflow execution.

## Summary

- **Seed generation** transforms BigBang interview transcripts into immutable specifications through a five-phase pipeline: ambiguity gating, LLM extraction, metadata creation, frozen model construction, and YAML persistence.
- The **0.2 ambiguity threshold** in [`bigbang/ambiguity.py`](https://github.com/Q00/ouroboros/blob/main/bigbang/ambiguity.py) acts as a quality gate, preventing unclear requirements from becoming seeds.
- The `Seed` Pydantic model uses `frozen=True` (defined in [`core/seed.py`](https://github.com/Q00/ouroboros/blob/main/core/seed.py)) to enforce runtime immutability, raising `ValidationError` on any modification attempt.
- **Evolution** is handled by `generate_from_reflect`, which creates new seeds with preserved parent lineage while keeping the original direction fields immutable.
- Complete auditability is maintained through `SeedMetadata`, which links every seed to its source interview and ambiguity score.

## Frequently Asked Questions

### What happens if the ambiguity score exceeds 0.2 during Seed generation?

The `SeedGenerator.generate` method rejects the operation and returns an error result. This prevents the creation of seeds from unclear or contradictory interview data, ensuring that only well-defined requirements enter the immutable workflow pipeline.

### How does the Seed model enforce immutability at the code level?

The `Seed` class in [`src/ouroboros/core/seed.py`](https://github.com/Q00/ouroboros/blob/main/src/ouroboros/core/seed.py) declares all fields with Pydantic's `frozen=True` configuration. This generates a `ValidationError` at runtime if any code attempts to modify seed attributes after instantiation, providing compile-time and runtime guarantees of immutability.

### Can a Seed be modified after it is created in Ouroboros?

No. Once instantiated, a Seed cannot be modified. To change requirements, the system creates a new Seed via `generate_from_reflect`, which copies the immutable direction from the parent while allowing ontology refinements. The original seed remains unchanged, preserving historical accuracy.

### How does Seed generation handle requirements evolution across workflow generations?

The `generate_from_reflect` method creates a new seed that references the original via `parent_seed_id` in the metadata. It preserves the parent's immutable direction (goals and constraints) while updating only the ontology based on reflection insights, maintaining a strict lineage chain for audit purposes.