Skip to content

SURFACE_GENERATION.md

Latest commit

 

History

History
358 lines (271 loc) · 9.83 KB

SURFACE_GENERATION.md

File metadata and controls

358 lines (271 loc) · 9.83 KB
Raw

Surface Generation: Chomsky's Deep/Surface Structure Separation

Overview

MLN now implements Chomsky's separation of deep structure and surface structure, a fundamental insight from transformational grammar that maps perfectly to AI:

Deep Structure (MKU)           Surface Structure (Natural Language)
─────────────────────         ────────────────────────────────────
Operational semantics    ──→   "Dog is a friendly mammal"
Predicates & properties  ──→   "A dog: domesticated mammal with bark"
Compositional form       ──→   "Dogs are domesticated animals that bark"
                         ──→   "Dog, a loyal companion of humankind"

Key Insight: ONE deep structure → MANY surface realizations

Why This Matters

Traditional LLMs

  • Only surface: Statistical patterns in text
  • No deep structure: Can't reason about semantics
  • Not compositional: Can't systematically generate variants

MLN Approach

  • Separates concerns: Deep (meaning) vs Surface (expression)
  • Operational semantics: MKUs have executable structure
  • Systematic generation: Transform deep→surface via rules
  • Explainable: You can trace why text was generated

Architecture

from src.surface_generator import create_surface_generator

# Built-in (no LLM required)
gen = create_surface_generator()

# With LLM (optional, richer output)
gen = create_surface_generator('openai', model='gpt-4')
gen = create_surface_generator('anthropic', model='claude-3-opus')
gen = create_surface_generator('ollama', model='llama2')

Generation Modes

  1. Built-in Transformational Rules (default)

    • No external dependencies
    • Fast, deterministic
    • Multiple styles: conversational, technical, educational, poetic
    • Works offline

  2. LLM-Enhanced (optional)

    • Richer, more natural output
    • Learns from examples
    • Context-aware
    • Falls back to built-in if unavailable

Usage Examples

Basic Usage

from src.surface_generator import create_surface_generator

gen = create_surface_generator()

# MKU deep structure
mku_data = {
    'concept_id': 'dog',
    'predicate': 'mammal',
    'properties': {
        'domesticated': True,
        'social': True,
        'barks': True
    },
    'relations': {
        'subtype': ['mammal', 'animal'],
        'similar_to': ['cat', 'wolf']
    }
}

# Generate surface forms
conversational = gen.generate_from_mku(mku_data, style='conversational')
# → "Dog is a mammal with domesticated: True, social: True. It has 4 relationships..."

technical = gen.generate_from_mku(mku_data, style='technical')
# → "dog: mammal(domesticated=True, social=True, barks=True) with 4 relations"

educational = gen.generate_from_mku(mku_data, style='educational')
# → "Dog is a type of mammal. It has these characteristics: domesticated is True..."

poetic = gen.generate_from_mku(mku_data, style='poetic')
# → "Dog, a mammal dancing in the web of knowledge, connected by invisible threads..."

Multiple Variants (Same Meaning)

# Generate 5 different ways to say the same thing
variants = gen.generate_multiple_variants(mku_data, num_variants=5)

for i, variant in enumerate(variants, 1):
    print(f"{i}. {variant}")

# Output:
# 1. Dog is a mammal with domesticated: True, social: True...
# 2. dog: mammal(domesticated=True, social=True...) with 4 relations
# 3. Dog is a type of mammal. It has these characteristics...
# 4. Dog is a mammal with domesticated: True, social: True...
# 5. dog: mammal(domesticated=True...) with 4 relations

Reasoning Chain Explanation

# Turn inference chain into natural language
chain = [
    {'concept_id': 'dog', 'predicate': 'mammal'},
    {'concept_id': 'mammal', 'predicate': 'animal'},
    {'concept_id': 'animal', 'predicate': 'living_thing'}
]

explanation = gen.generate_with_reasoning_chain(
    chain, 
    "Therefore, dog is a living_thing"
)
# → "Reasoning: Starting from dog, then mammal, then animal, we conclude: 
#    Therefore, dog is a living_thing"

Chatbot Integration

from src.chatbot import ConsciousnessChatbot
from src.surface_generator import SurfaceGenerationConfig

# With built-in generation (default)
bot = ConsciousnessChatbot()

# With LLM-powered generation (optional)
config = SurfaceGenerationConfig(provider='openai', model='gpt-4')
bot = ConsciousnessChatbot(surface_config=config)

response = bot.ask("What is a dog?")
print(response.answer)
# Uses transformational grammar to generate natural explanation

Configuration

Built-in (No Configuration Needed)

gen = create_surface_generator()  # That's it!

OpenAI

# Set environment variable
export OPENAI_API_KEY='sk-...'

# Or pass directly
from src.surface_generator import SurfaceGenerationConfig

config = SurfaceGenerationConfig(
    provider='openai',
    model='gpt-4',
    temperature=0.7,
    max_tokens=150
)
gen = SurfaceGenerator(config)

Anthropic (Claude)

export ANTHROPIC_API_KEY='sk-ant-...'

config = SurfaceGenerationConfig(
    provider='anthropic',
    model='claude-3-opus-20240229',
    temperature=0.8
)

Ollama (Local)

# No API key needed!
config = SurfaceGenerationConfig(
    provider='ollama',
    model='llama2',
    base_url='http://localhost:11434'
)

Styles

Style Use Case Example
conversational Chat, Q&A "Dog is a friendly mammal with..."
technical Documentation "dog: mammal(domesticated=True)..."
educational Teaching "Dog is a type of mammal. It has characteristics..."
poetic Creative "Dog, a mammal dancing in the web..."

Comparison: Built-in vs LLM

Feature Built-in LLM-Powered
Dependencies None API key / Ollama
Speed Fast (~1ms) Slower (100-500ms)
Offline ✅ Yes ❌ Requires connection
Cost Free API costs
Output quality Good Excellent
Consistency Deterministic Variable
Fallback N/A → Built-in

Recommendation: Start with built-in (works great!), add LLM if you need richer outputs.

Running the Demo

# Full demo (built-in + LLM if keys available)
python examples/surface_generation_demo.py

# Just test the module
python src/surface_generator.py

API Reference

SurfaceGenerator

class SurfaceGenerator:
    def __init__(self, config: Optional[SurfaceGenerationConfig] = None)
    
    def generate_from_mku(
        self, 
        mku_data: Dict[str, Any],
        context: Optional[str] = None,
        style: Optional[str] = None
    ) -> str
    
    def generate_multiple_variants(
        self,
        mku_data: Dict[str, Any],
        num_variants: int = 3,
        styles: Optional[List[str]] = None
    ) -> List[str]
    
    def generate_with_reasoning_chain(
        self,
        inference_chain: List[Dict[str, Any]],
        conclusion: str
    ) -> str

SurfaceGenerationConfig

@dataclass
class SurfaceGenerationConfig:
    provider: str = 'none'  # 'openai', 'anthropic', 'ollama', 'none'
    model: str = 'gpt-3.5-turbo'
    api_key: Optional[str] = None
    base_url: Optional[str] = None  # For Ollama
    temperature: float = 0.7
    max_tokens: int = 150
    style: str = 'conversational'

Factory Function

def create_surface_generator(
    provider: str = 'none',
    model: Optional[str] = None,
    **kwargs
) -> SurfaceGenerator

Implementation Details

Transformational Grammar Rules

The built-in generator implements simple but effective transformational rules:

  1. Conversational: {concept} is a {predicate} with {key_properties}. It has {n} relationships...
  2. Technical: {concept}: {predicate}({all_properties}) with {n} relations
  3. Educational: {concept} is a type of {predicate}. It has characteristics: {properties}...
  4. Poetic: {concept}, a {predicate} dancing in the web of knowledge...

LLM Prompting Strategy

When LLM is enabled:

You are a surface structure generator for a knowledge representation system.
Given a deep structure (symbolic, compositional), generate natural language.

Deep Structure:
- Concept: {concept_id}
- Predicate: {predicate}
- Properties: {json_properties}
- Relations: {json_relations}

[Style-specific instructions]

Generate ONLY the natural language output, no preamble.

Philosophy

Why Separate Deep and Surface?

  1. Compositionality: Deep structure is compositional (you can reason about it)
  2. Flexibility: One meaning, many expressions
  3. Explainability: You know WHY something was generated
  4. Editability: Change deep structure, all surfaces update

Connection to Chomsky

Chomsky showed that:

  • All languages have deep structure (universal grammar)
  • Surface structure varies (English, Spanish, etc.)
  • Transformational rules map deep → surface

MLN applies this to AI:

  • All knowledge has deep structure (MKU semantics)
  • Surface structure varies (text, code, visualizations)
  • Generation rules map deep → surface

Future Enhancements

  • Code generation (deep → Python/JS/SQL)
  • Visualization descriptions (deep → D3.js/chart instructions)
  • Speech synthesis integration
  • Fine-tuned models for domain-specific generation
  • Multi-lingual surface generation
  • Style transfer (keep meaning, change tone/formality)

References

  • Chomsky, N. (1957). Syntactic Structures
  • Chomsky, N. (1965). Aspects of the Theory of Syntax
  • This implementation: src/surface_generator.py
  • Demo: examples/surface_generation_demo.py
  • Integration: src/chatbot.py

Status: ✅ Implemented (v1.3.0)
Tested: ✅ All styles working
Optional: ✅ Works with or without LLM
Production-ready: ✅ Yes