Table of Contents #

• The Problem
• The Solution
• Quick Start
• How It Works
• Features
• Complete Example
• API Reference
• Robustness
• LLM Provider Setup
• Contributing
• License

The Problem #

LLM APIs stream responses token-by-token. When the response is JSON, you get incomplete fragments:

jsonDecode() fails on partial JSON. Your options aren't great:

The Solution #

LLM JSON Stream parses JSON character-by-character as it arrives, allowing you to subscribe to specific properties and react to their values the moment they're available.

Instead of waiting for the entire JSON response to complete, you can:

• Display text fields progressively as they stream in
• Add list items to your UI the instant they begin parsing
• Await complete values for properties that need them (like IDs or flags)

Quick Start #

# pubspec.yaml
dependencies:
  llm_json_stream: ^0.2.3

import 'package:llm_json_stream/json_stream_parser.dart';

final parser = JsonStreamParser(llmResponseStream);

// Stream text as it types
parser.getStringProperty('message').stream.listen((chunk) {
  displayText += chunk;  // Update UI character-by-character
});

// Or get the complete value
final title = await parser.getStringProperty('title').future;

// Clean up when done
await parser.dispose();

How It Works #

Two APIs for Every Property #

Every property gives you both a stream (incremental updates) and a future (complete value):

final title = parser.getStringProperty('title');

title.stream.listen((chunk) => ...);  // Each chunk as it arrives
final complete = await title.future;   // The final value

Path Syntax #

Navigate JSON with dot notation and array indices:

parser.getStringProperty('title')                    // Root property
parser.getStringProperty('user.name')                // Nested object
parser.getStringProperty('items[0].title')           // Array element
parser.getNumberProperty('data.users[2].age')        // Deep nesting

Feature Highlights #

🔤 Streaming Strings #

Display text as the LLM generates it, creating a smooth typing effect:

parser.getStringProperty('response').stream.listen((chunk) {
  setState(() => displayText += chunk);
});

📋 Reactive Lists #

An underrated but powerful feature. Add items to your UI the instant parsing begins—even before their content arrives:

parser.getListProperty('articles').onElement((article, index) {
  // Fires IMMEDIATELY when "[{" is detected
  setState(() => articles.add(ArticleCard.loading()));
  
  // Fill in content as it streams
  article.asMap.getStringProperty('title').stream.listen((chunk) {
    setState(() => articles[index].title += chunk);
  });
});

Traditional parsers wait for complete objects → jarring UI jumps.
This approach → smooth loading states that populate progressively.

🎯 All JSON Types #

parser.getStringProperty('name')      // String → streams chunks
parser.getNumberProperty('age')       // Number → int or double
parser.getBooleanProperty('active')   // Boolean  
parser.getNullProperty('deleted')     // Null
parser.getMapProperty('config')       // Object → Map<String, dynamic>
parser.getListProperty('tags')        // Array → List<dynamic>

⛓️ Flexible API #

Navigate complex structures with a fluent interface:

// Chain getters together
final user = parser.getMapProperty('user');
final name = await user.getStringProperty('name').future;
final email = await user.getStringProperty('email').future;

// Or go deep in one line
final city = await parser.map('user').map('address').str('city').future;

// Or be normal
final age = await parser.str('user.age').future;

🎭 Smart Casts #

Handle dynamic list elements with type casts:

parser.getListProperty('items').onElement((element, index) {
  element.asMap.getStringProperty('title').stream.listen(...);
  element.asMap.getNumberProperty('price').future.then(...);
});

Available: .asMap, .asList, .asStr, .asNum, .asBool, .asNull

Complete Example #

A realistic scenario: parsing a blog post with streaming title and reactive sections.

import 'package:llm_json_stream/json_stream_parser.dart';

void main() async {
  // Your LLM stream (OpenAI, Claude, Gemini, etc.)
  final stream = llm.streamChat("Generate a blog post as JSON");
  
  final parser = JsonStreamParser(stream);
  
  // Title streams character-by-character
  parser.getStringProperty('title').stream.listen((chunk) {
    print(chunk);  // "H" "e" "l" "l" "o" " " "W" "o" "r" "l" "d"
  });
  
  // Sections appear the moment they start
  parser.getListProperty('sections').onElement((section, index) {
    print('Section $index detected!');
    
    section.asMap.getStringProperty('heading').stream.listen((chunk) {
      print('  Heading chunk: $chunk');
    });
    
    section.asMap.getStringProperty('body').stream.listen((chunk) {
      print('  Body chunk: $chunk');
    });
  });
  
  // Wait for completion
  final allSections = await parser.getListProperty('sections').future;
  print('Done! Got ${allSections.length} sections');
  
  await parser.dispose();
}

API Reference #

Property Methods #

PropertyStream Interface #

.stream   // Stream<T> — values/chunks as they arrive
.future   // Future<T> — completes with final value

ListPropertyStream #

.onElement((element, index) => ...)  // Callback when element parsing starts

Smart Casts #

.asMap    // → MapPropertyStream
.asList   // → ListPropertyStream  
.asStr    // → StringPropertyStream
.asNum    // → NumberPropertyStream
.asBool   // → BooleanPropertyStream

Cleanup #

Always dispose the parser when you're done:

await parser.dispose();

Robustness #

Battle-tested with 338 tests. Handles real-world edge cases:

LLM Provider Setup #

final response = await openai.chat.completions.create(
  model: 'gpt-4',
  messages: messages,
  stream: true,
);

final jsonStream = response.map((chunk) => 
  chunk.choices.first.delta.content ?? ''
);

final parser = JsonStreamParser(jsonStream);

final stream = anthropic.messages.stream(
  model: 'claude-3-opus',
  messages: messages,
);

final jsonStream = stream.map((event) => event.delta?.text ?? '');
final parser = JsonStreamParser(jsonStream);

final response = model.generateContentStream(prompt);
final jsonStream = response.map((chunk) => chunk.text ?? '');
final parser = JsonStreamParser(jsonStream);

Contributing #

Contributions welcome!

1. Check open issues
2. Open an issue before major changes
3. Run dart test before submitting
4. Match existing code style

License #

MIT — see LICENSE