Atomizer/examples/README_INTERACTIVE_SESSION.md

Interactive Research Agent Session

Overview

The Interactive Research Agent allows you to interact with the AI-powered Research Agent through a conversational CLI interface. The agent can learn from examples you provide and automatically generate code for new optimization features.

Quick Start

Run the Interactive Session

python examples/interactive_research_session.py

Try the Demo

When the session starts, type demo to see an automated demonstration:

💬 Your request: demo

The demo will show:

1. Learning from Example: Agent learns XML material structure from a steel example
2. Code Generation: Automatically generates Python code (81 lines)
3. Knowledge Reuse: Second request reuses learned knowledge (no example needed!)

How to Use

Making Requests

Simply type your request in natural language:

💬 Your request: Create an NX material XML generator for aluminum

The agent will:

1. Analyze what it knows and what's missing
2. Ask for examples if it needs to learn something new
3. Search its knowledge base for existing patterns
4. Generate code from learned templates
5. Save the generated feature to a file

Providing Examples

When the agent asks for an example, you have 3 options:

1. Provide a file path:

   Your choice: examples/my_example.xml
   

2. Paste content directly:

   Your choice: <?xml version="1.0"?>
   <MyExample>...</MyExample>
   

3. Skip (if you don't have an example):

   Your choice: skip
   

Understanding the Output

The agent provides visual feedback at each step:

• 🔍 Knowledge Gap Analysis: Shows what's missing and confidence level
• 📋 Research Plan: Steps the agent will take to gather knowledge
• 🧠 Knowledge Synthesized: What the agent learned (schemas, patterns)
• 💻 Code Generation: Preview of generated Python code
• 💾 Files Created: Where the generated code was saved

Confidence Levels

• < 50%: New domain - Learning required (will ask for examples)
• 50-80%: Partial knowledge - Some research needed
• > 80%: Known domain - Can reuse existing knowledge

Example Session

================================================================================
🤖 Interactive Research Agent Session
================================================================================

  Welcome! I'm your Research Agent. I can learn from examples and
  generate code for optimization features.

  Commands:
    • Type your request in natural language
    • Type 'demo' for a demonstration
    • Type 'quit' to exit

💬 Your request: Create NX material XML for titanium Ti-6Al-4V

--------------------------------------------------------------------------------
[Step 1] Analyzing Knowledge Gap
--------------------------------------------------------------------------------

  🔍 Knowledge Gap Analysis:

  Missing Features (1):
    • new_feature_required

  Missing Knowledge (1):
    • material

  Confidence Level: 80%
  📊 Status: Known domain - Can reuse existing knowledge

--------------------------------------------------------------------------------
[Step 2] Executing Research Plan
--------------------------------------------------------------------------------

  📋 Research Plan Created:

  I'll gather knowledge in 2 steps:

  1. 📚 Search Knowledge Base
     Expected confidence: 80%
     Search query: "material XML NX"

  2. 👤 Ask User For Example
     Expected confidence: 95%
     What I'll ask: "Could you provide an example of an NX material XML file?"

  ⚡ Executing Step 1/2: Search Knowledge Base
  ----------------------------------------------------------------------------
  🔍 Searching knowledge base for: "material XML NX"
  ✓ Found existing knowledge! Session: 2025-11-16_nx_materials_demo
    Confidence: 95%, Relevance: 85%

  ⚡ Executing Step 2/2: Ask User For Example
  ----------------------------------------------------------------------------
  ⊘ Skipping - Already have high confidence from knowledge base

--------------------------------------------------------------------------------
[Step 3] Synthesizing Knowledge
--------------------------------------------------------------------------------

  🧠 Knowledge Synthesized:

  Overall Confidence: 95%

  📄 Learned XML Structure:
    Root element: <PhysicalMaterial>
    Attributes: {'name': 'Steel_AISI_1020', 'version': '1.0'}
    Required fields (5):
      • Density
      • YoungModulus
      • PoissonRatio
      • ThermalExpansion
      • YieldStrength

--------------------------------------------------------------------------------
[Step 4] Generating Feature Code
--------------------------------------------------------------------------------

  🔨 Designing feature: create_nx_material_xml_for_t
    Category: engineering
    Lifecycle stage: all
    Input parameters: 5

  💻 Generating Python code...
    Generated 2327 characters (81 lines)
    ✓ Code is syntactically valid Python

  💾 Saved to: optimization_engine/custom_functions/create_nx_material_xml_for_t.py

================================================================================
✓ Request Completed Successfully!
================================================================================

  Generated file: optimization_engine/custom_functions/create_nx_material_xml_for_t.py
  Knowledge confidence: 95%
  Session saved: 2025-11-16_create_nx_material_xml_for_t

💬 Your request: quit

  👋 Goodbye! Session ended.

Key Features

1. Knowledge Accumulation

• Agent remembers what it learns across sessions
• Second similar request doesn't require re-learning
• Knowledge base grows over time

2. Intelligent Research Planning

• Prioritizes reliable sources (user examples > MCP > web)
• Creates step-by-step research plan
• Explains what it will do before doing it

3. Pattern Recognition

• Extracts XML schemas from examples
• Identifies Python code patterns (functions, classes, imports)
• Learns relationships between inputs and outputs

4. Code Generation

• Generates complete Python modules with:
  • Docstrings and documentation
  • Type hints for all parameters
  • Example usage code
  • Error handling
• Code is syntactically validated before saving

5. Session Documentation

• Every research session is automatically documented
• Includes: user question, sources, findings, decisions
• Searchable for future knowledge retrieval

Advanced Usage

Auto Mode (for Testing)

For automated testing, you can run the session in auto-mode:

from examples.interactive_research_session import InteractiveResearchSession

session = InteractiveResearchSession(auto_mode=True)
session.run_demo()  # Runs without user input prompts

Programmatic Usage

You can also use the Research Agent programmatically:

from optimization_engine.research_agent import ResearchAgent

agent = ResearchAgent()

# Identify what's missing
gap = agent.identify_knowledge_gap("Create NX modal analysis")

# Search existing knowledge
existing = agent.search_knowledge_base("modal analysis")

# Create research plan
plan = agent.create_research_plan(gap)

# ... execute plan and synthesize knowledge

Troubleshooting

"No matching session found"

• This is normal for new domains the agent hasn't seen before
• The agent will ask for an example to learn from

"Confidence too low to generate code"

• Provide more detailed examples
• Try providing multiple examples of the same pattern
• Check that your example files are well-formed

"Generated code has syntax errors"

• This is rare and indicates a bug in code generation
• Please report this with the example that caused it

What's Next

The interactive session currently includes:

• ✅ Knowledge gap detection
• ✅ Knowledge base search and retrieval
• ✅ Learning from user examples
• ✅ Python code generation
• ✅ Session documentation

Coming in future phases:

• 🔜 MCP server integration (query NX documentation)
• 🔜 Web search integration (search online resources)
• 🔜 Multi-turn conversations with context
• 🔜 Code refinement based on feedback
• 🔜 Feature validation and testing

Testing

Run the automated test:

python tests/test_interactive_session.py

This will demonstrate the complete workflow including:

• Learning from an example (steel material XML)
• Generating working Python code
• Reusing knowledge for a second request
• All without user interaction

Support

For issues or questions:

• Check the existing research sessions in knowledge_base/research_sessions/
• Review generated code in optimization_engine/custom_functions/
• See test examples in tests/test_*.py