DEV Community: Nam Tran

Introducing Home Screen Widgets in PhoneCleanKit

Nam Tran — Mon, 26 Jan 2026 15:52:57 +0000

Countdown events, track time, monitor storage, and stay focused — all from your Home Screen.

We are excited to announce that PhoneCleanKit now includes four Home Screen Widgets to enhance your daily iPhone, iPad experience. What started as a storage cleaner has grown into a toolkit you can use every day.

Why We Built Widgets

PhoneCleanKit helps you find similar photos, large files, screenshots, and more. But we wanted to give you more reasons to keep the app on your device beyond occasional cleanups.

With these widgets, PhoneCleanKit becomes part of your daily routine — not just something you open when storage runs low.

Four Widgets for Everyday Use

Storage Widget

Monitor your iPhone/iPad storage at a glance. See your storage percentage with a clean circular progress ring and how much free space you have left. Tap the refresh button to fetch fresh data instantly, or tap the widget to open the app and start cleaning.

Available in small, medium, and large sizes.

Countdown Event Widget

Never miss an important date. Set countdowns for birthdays, holidays, project deadlines, vacations, or any event that matters to you. Watch the days tick down right from your Home Screen.

Flip Clock Widget

A beautiful retro-style clock for your Home Screen. If you appreciate classic design, this widget brings that nostalgic flip clock aesthetic to your iPhone. Simple, elegant, and always on display.

Pomodoro Timer Widget

Stay focused with the Pomodoro technique. Start a 25-minute focus session directly from your Home Screen. Perfect for work, study, or any task that needs your full attention. No need to open the app — just tap and focus.

Interactive Widgets: The iOS 17+ Game Changer

Before iOS 17, widgets were essentially static displays. Tapping anywhere on a widget would simply open the app. You could not interact with individual buttons inside the widget.

Starting with iOS 17, Apple introduced interactive widgets powered by App Intents. This means buttons inside widgets can now perform actions directly without launching the app.

In PhoneCleanKit, we use this for our Refresh button on the Storage Widget and the Start button on the Pomodoro Timer. When you tap them, the action happens immediately. No app launch, no interruption to what you are doing.

Here is how simple it is to create an interactive button with App Intents:

struct RefreshStorageIntent: AppIntent {
    static var title: LocalizedStringResource = "Refresh Storage"
    static var openAppWhenRun: Bool = false  // Key: stays on Home Screen

    func perform() async throws -> some IntentResult {
        return .result()
    }
}

Then in the widget view, just attach the intent to a button:

Button(intent: RefreshStorageIntent()) {
    Image(systemName: "arrow.clockwise")
}

The system handles the rest. One tap and the action completes right from the Home Screen.

How to Add the Widgets

Long-press on your Home Screen until apps jiggle
Tap the + button in the top corner
Search for "PhoneCleanKit"
Choose your preferred widget: Storage, Countdown, Flip Clock, or Pomodoro
Select your preferred size
Tap Add Widget

Try It Today

All four widgets are available now in PhoneCleanKit. Download the app and add them to your Home Screen to make your iPhone more useful every day.

PhoneCleanKit

Also available: DiskCleanKit for Mac — clean up your Mac storage with the same simplicity.

# 🪦 RIP CocoaPods (2011-2026): What Every iOS Developer Must Do NOW

Nam Tran — Mon, 26 Jan 2026 06:32:24 +0000

After 15 years of faithful service, CocoaPods is officially dying.

On December 2, 2026, the CocoaPods trunk will become permanently read-only. No new pods. No updates. Game over.

If you're an iOS developer, React Native developer, or Flutter developer — this affects YOU. Here's your complete survival guide.

📢

What	Details
💀 Death Date	December 2, 2026
❌ What Stops	New pods, updates to existing pods
✅ What Still Works	Existing projects (for now)
🎯 Your Action	Migrate to Swift Package Manager
⏰ Time Left	~11 months

📰 The Official Announcement

From Orta Therox, CocoaPods maintainer:

"In two years we plan to turn CocoaPods trunk to be read-only. At that point, no new versions or pods will be added to trunk."

— CocoaPods Blog, November 2024

This isn't speculation. This is official.

📅 The Complete Timeline

┌─────────────────────────────────────────────────────────────┐
│                    COCOAPODS SUNSET TIMELINE                 │
├─────────────────────────────────────────────────────────────┤
│  ✅ Aug 2024    │ Maintenance mode announced                │
│  ✅ Nov 2024    │ Read-only plan confirmed                  │
│  ✅ May 2025    │ prepare_command blocked (security)        │
│  ⏳ Mid-late 2025│ First mass notification to contributors  │
│  ⏳ Sept-Oct 2026│ Final warning notification               │
│  ⏳ Nov 1-7 2026 │ Test run of read-only mode               │
│  💀 Dec 2, 2026  │ TRUNK PERMANENTLY READ-ONLY              │
└─────────────────────────────────────────────────────────────┘

Why December 2nd? It's the Wednesday after American Thanksgiving — chosen so developers won't be in "rush mode."

🤔 Why Is CocoaPods Dying?

1. Swift Package Manager Won

When Apple introduced SPM in 2015, CocoaPods' fate was sealed:

+ ✅ SPM: Built into Xcode
+ ✅ SPM: No Ruby dependency
+ ✅ SPM: Apple's official support
+ ✅ SPM: Better security model
+ ✅ SPM: Faster resolution

- ❌ CocoaPods: External tool
- ❌ CocoaPods: Ruby dependency hell
- ❌ CocoaPods: Community maintained
- ❌ CocoaPods: Security vulnerabilities
- ❌ CocoaPods: Slower builds

2. Maintainer Burnout

From the official blog:

"Members of the core team have individually had reasons for continual maintenance: a sense of duty, being employed to work on libraries or apps which use CocoaPods... However, with time — these links become more tenuous too, jobs change, people move to new ecosystems."

The team is tired. And rightfully so after 15 years.

3. Security Nightmares

In May 2025, CocoaPods had to block the prepare_command field because security researchers kept exploiting it:

"We've had enough security researchers abusing scripting capabilities in CocoaPods that we are now introducing a block on allowing new CocoaPods to use the prepare_command field."

4. The Irony: Cross-Platform Kept It Alive

Here's the twist:

"If CocoaPods' only audience were native Cocoa developers, CocoaPods' usage should be on the decline. The popularity of React Native and Flutter have ensured that most metrics of usage/traffic have been steadily rising over time."

React Native and Flutter developers — you're the reason CocoaPods lasted this long!

✅ What Will STILL Work After Dec 2026

Don't panic completely. These will continue working:

// ✅ STILL WORKS
pod install                    // Existing pods
pod update                     // To versions already on trunk
// Pods from GitHub/jsDelivr
// Private spec repositories  
// Vendored dependencies (from npm)

Why? The infrastructure stays online as long as GitHub and jsDelivr exist.

❌ What Will BREAK

// ❌ BROKEN
pod trunk push MyAwesomePod   // New pods rejected
pod trunk push --version 2.0   // Updates rejected
// Security patches via trunk
// New library releases

🚨 Who Should Be MOST Worried?

🔴 HIGH PRIORITY — Migrate NOW

Developer Type	Why You're at Risk
Library Maintainers	Your users need SPM support yesterday
Enterprise Teams	Security updates = critical
New Projects	Don't start with dead tech
React Native iOS	Google Maps dropping CocoaPods Q2 2026

🟡 MEDIUM PRIORITY — Plan Your Migration

Developer Type	Your Situation
Existing Production Apps	Works now, but plan ahead
Flutter Developers	Flutter team working on SPM
Private Spec Repo Users	More runway, but still migrate

🟢 LOW PRIORITY — You Have Time

Developer Type	Why You're OK
Fully Vendored Dependencies	Not dependent on trunk
Internal-only Libraries	Private repos keep working

🛠️ Complete Migration Guide: CocoaPods → SPM

Step 1: Audit Your Dependencies

First, list everything you're using:

# See all your pods
cat Podfile | grep "pod '"

# Or from Podfile.lock
cat Podfile.lock | grep "  -" | head -20

Create a migration spreadsheet:

Pod Name	Version	SPM Support?	Alternative
Alamofire	5.8.0	✅ Yes	—
Firebase	10.x	✅ Yes	—
Charts	5.0	✅ Yes	—
SomeLegacyPod	1.2	❌ No	Fork it

Step 2: Check SPM Availability

Quick resources:

Swift Package Index — Search 6,000+ packages
GitHub README — Look for "Swift Package Manager" section
Podspec source field — Get the Git URL

# Most libraries with SPM support have this file
ls Package.swift  # in the repo root

Step 3: Remove CocoaPods (The Clean Way)

# Install deintegration tools
sudo gem install cocoapods-deintegrate cocoapods-clean

# Navigate to your project
cd /path/to/your/project/ios

# Remove CocoaPods integration
pod deintegrate

# Clean cache
pod cache clean --all

# Delete leftover files
rm -rf Pods/
rm Podfile
rm Podfile.lock
rm -rf *.xcworkspace

# Now open .xcodeproj (not workspace!)
open YourApp.xcodeproj

Step 4: Add SPM Dependencies

In Xcode:

File → Add Package Dependencies...
Enter repo URL: https://github.com/Alamofire/Alamofire.git
Select version rule (e.g., "Up to Next Major")
Choose target(s)
Click Add Package

Or via Package.swift (for libraries):

// swift-tools-version:5.9
import PackageDescription

let package = Package(
    name: "MyAwesomeApp",
    platforms: [
        .iOS(.v15),
        .macOS(.v12)
    ],
    dependencies: [
        .package(url: "https://github.com/Alamofire/Alamofire.git", 
                 from: "5.8.0"),
        .package(url: "https://github.com/firebase/firebase-ios-sdk.git", 
                 from: "10.0.0"),
        .package(url: "https://github.com/realm/realm-swift.git", 
                 from: "10.45.0"),
    ],
    targets: [
        .target(
            name: "MyAwesomeApp",
            dependencies: [
                "Alamofire",
                .product(name: "FirebaseAnalytics", package: "firebase-ios-sdk"),
                .product(name: "RealmSwift", package: "realm-swift"),
            ]
        ),
    ]
)

Step 5: Handle Libraries WITHOUT SPM Support

Option A: Use XCFramework

// Package.swift
.binaryTarget(
    name: "SomeSDK",
    path: "Frameworks/SomeSDK.xcframework"
)

Option B: Fork and Add SPM Support

// Use your fork temporarily
.package(url: "https://github.com/YOUR_USERNAME/legacy-lib.git", 
         branch: "add-spm-support")

Then submit a PR to the original repo!

Option C: Vendor the Code

Copy source files directly into your project. Check the license first!

🔥 React Native Developers: Special Section

The Deprecation Warning You've Seen

==================== DEPRECATION NOTICE =====================
Calling `pod install` directly is deprecated in React Native
============================================================

This is intentional. React Native is preparing for the post-CocoaPods world.

New Commands to Use

# ❌ OLD WAY (deprecated)
cd ios && pod install

# ✅ NEW WAY
yarn ios
# or
npx react-native run-ios
# or (Expo)
npx expo run:ios

React Native 0.75+ SPM Integration

React Native 0.75 introduced spm_dependency helper:

# In your library's .podspec
Pod::Spec.new do |s|
  s.name = "MyRNLibrary"
  # ...

  spm_dependency(s,
    url: 'https://github.com/example/package.git',
    requirement: {kind: 'upToNextMajorVersion', minimumVersion: '1.0.0'},
    products: ['SomeProduct']
  )
end

⚠️ Google Maps SDK Warning

Google announced:

"Starting with version 11.0 of all Google Maps Platform iOS SDKs, new versions will not be released on CocoaPods." (Q2 2026)

If you use react-native-maps with Google provider — watch this closely.

Alternative: Use Apple Maps (no provider prop needed).

📱 Flutter Developers: What to Know

Flutter also relies on CocoaPods for iOS. The Flutter team is actively working on SPM:

Track progress: flutter/flutter#126005
Many plugins already support SPM
Migration tools in development

For now: Keep using CocoaPods but monitor Flutter's SPM progress.

📦 For Library Maintainers: Add SPM Support TODAY

Your users need this. Here's how:

1. Create Package.swift

// swift-tools-version:5.9
import PackageDescription

let package = Package(
    name: "MyAwesomeLibrary",
    platforms: [
        .iOS(.v13),
        .macOS(.v10_15),
        .tvOS(.v13),
        .watchOS(.v6)
    ],
    products: [
        .library(
            name: "MyAwesomeLibrary",
            targets: ["MyAwesomeLibrary"]
        ),
    ],
    targets: [
        .target(
            name: "MyAwesomeLibrary",
            path: "Sources"
        ),
        .testTarget(
            name: "MyAwesomeLibraryTests",
            dependencies: ["MyAwesomeLibrary"],
            path: "Tests"
        ),
    ]
)

2. Reorganize Your Files

SPM expects this structure:

MyLibrary/
├── Package.swift           # NEW
├── Sources/
│   └── MyAwesomeLibrary/
│       ├── File1.swift
│       ├── File2.swift
│       └── Resources/      # If needed
├── Tests/
│   └── MyAwesomeLibraryTests/
│       └── Tests.swift
└── MyLibrary.podspec       # Keep for backward compatibility

3. Test Locally

swift build
swift test
swift package resolve

4. Tag a Release

git add Package.swift Sources/ Tests/
git commit -m "Add Swift Package Manager support"
git tag 2.0.0
git push origin main --tags

✅ Migration Checklist

Copy this for your project:

## Pre-Migration
- [ ] List all CocoaPods dependencies
- [ ] Check SPM support for each
- [ ] Find alternatives for unsupported libs
- [ ] Create backup branch
- [ ] Notify team members

## Migration
- [ ] Run `pod deintegrate`
- [ ] Delete Pods/, Podfile, Podfile.lock, *.xcworkspace
- [ ] Open .xcodeproj
- [ ] Add each dependency via SPM
- [ ] Update import statements if needed
- [ ] Fix build errors

## Post-Migration  
- [ ] Run all unit tests
- [ ] Run all UI tests
- [ ] Test on real devices (iPhone + iPad)
- [ ] Test CI/CD pipeline
- [ ] Update README.md
- [ ] Update onboarding docs
- [ ] Celebrate 🎉

💡 Pro Tips from the Trenches

1. Don't Wait Until November 2026

Library maintainers won't magically add SPM support at the last minute. Start now.

2. Migrate One Dependency at a Time

# Podfile - Gradual migration
target 'MyApp' do
  # Already migrated to SPM:
  # - Alamofire
  # - Firebase

  # Still on CocoaPods:
  pod 'SomeLegacyLib', '~> 1.0'
end

3. Test on Fresh Clones

SPM resolves differently than CocoaPods. Always test:

# Simulate a new developer
git clone your-repo fresh-clone
cd fresh-clone
open Project.xcodeproj
# Build and run

4. Update Your CI/CD

Before (CocoaPods):

- run: pod install
- run: xcodebuild -workspace App.xcworkspace ...

After (SPM):

- run: xcodebuild -project App.xcodeproj -resolvePackageDependencies
- run: xcodebuild -project App.xcodeproj ...

5. For New Projects: SPM Only

Starting a new project in 2026+? Don't even install CocoaPods.

# Just use Xcode's built-in package management
# File → Add Package Dependencies...

🔗 Essential Resources

Resource	Link
Official Announcement	blog.cocoapods.org
SPM Documentation	swift.org/package-manager
Swift Package Index	swiftpackageindex.com
Apple: Adding Packages	developer.apple.com
RN New Architecture	reactnative.dev

🎬 Conclusion

CocoaPods was a game-changer. It transformed iOS development by making dependency management accessible to everyone. Before CocoaPods, integrating third-party libraries was a nightmare of manual file copying and build configuration.

But technology evolves. Swift Package Manager is:

Faster
More secure
Native to Xcode
Backed by Apple

The clock is ticking. December 2, 2026 will arrive faster than you think.

┌────────────────────────────────────────┐
│                                        │
│   Time remaining: ~11 months           │
│                                        │
│   Start your migration TODAY.          │
│                                        │
│   Your future self will thank you.     │
│                                        │
└────────────────────────────────────────┘

Thank you, CocoaPods, for 15 incredible years. 🪦💐

Build Your Own AI Story Generator with RAG - Part 3: Generating Stories

Nam Tran — Mon, 26 Jan 2026 01:18:22 +0000

We've built our RAG pipeline (Part 1, Part 2). Now let's use it to generate stories.

In this final article, we'll:

Connect to LLMs (local and cloud)
Build augmented prompts
Generate multi-chapter stories
Maintain consistency across chapters

Source Code: github.com/namtran/ai-rag-tutorial-story-generator

The Generation Flow

┌─────────────────────────────────────────────────────────────┐
│                   STORY GENERATION                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  User: "Write about a young cultivator finding a cave"     │
│                         │                                   │
│                         ▼                                   │
│  ┌─────────────────────────────────────────┐               │
│  │  1. EMBED QUERY                         │               │
│  │     Convert prompt → vector             │               │
│  └─────────────────────────────────────────┘               │
│                         │                                   │
│                         ▼                                   │
│  ┌─────────────────────────────────────────┐               │
│  │  2. RETRIEVE                            │               │
│  │     Find similar passages in ChromaDB   │               │
│  │     Returns: 3-5 style samples          │               │
│  └─────────────────────────────────────────┘               │
│                         │                                   │
│                         ▼                                   │
│  ┌─────────────────────────────────────────┐               │
│  │  3. AUGMENT PROMPT                      │               │
│  │     "Here are style examples:           │               │
│  │      [retrieved passages]               │               │
│  │      Now write: [user prompt]"          │               │
│  └─────────────────────────────────────────┘               │
│                         │                                   │
│                         ▼                                   │
│  ┌─────────────────────────────────────────┐               │
│  │  4. GENERATE                            │               │
│  │     Send to LLM (Ollama/OpenAI)         │               │
│  │     Generate story with learned style   │               │
│  └─────────────────────────────────────────┘               │
│                         │                                   │
│                         ▼                                   │
│  ┌─────────────────────────────────────────┐               │
│  │  OUTPUT:                                │               │
│  │  "Chen Wei pushed aside the waterfall,  │               │
│  │   revealing a cave mouth wreathed in    │               │
│  │   ancient qi. His cultivation base      │               │
│  │   trembled as Heaven's Will..."         │               │
│  └─────────────────────────────────────────┘               │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Step 1: The Style Retriever

First, let's build a class to retrieve relevant passages:

# generate_with_style.py

from sentence_transformers import SentenceTransformer
import chromadb
from config import CHROMA_DIR, EMBED_MODEL, COLLECTION_NAME

class StyleRetriever:
    """Retrieve writing styles from ChromaDB"""

    def __init__(self):
        self.embedder = SentenceTransformer(EMBED_MODEL)
        self.client = chromadb.PersistentClient(path=str(CHROMA_DIR))
        self.collection = self.client.get_collection(COLLECTION_NAME)

        print(f"[RAG] Connected: {self.collection.count()} chunks")

    def retrieve(self, query: str, n_results: int = 3) -> list[str]:
        """Find passages with similar writing style"""
        # Embed the query
        query_embedding = self.embedder.encode([query])

        # Search ChromaDB
        results = self.collection.query(
            query_embeddings=query_embedding.tolist(),
            n_results=n_results
        )

        return results['documents'][0]

Usage:

retriever = StyleRetriever()
passages = retriever.retrieve("A young warrior discovers a magical sword")

for p in passages:
    print(p[:200] + "...")

Step 2: LLM Backends

We support multiple LLM backends. Let's implement two: Ollama (local) and OpenAI (cloud).

Ollama Generator (Local)

class OllamaGenerator:
    """Generate text using local Ollama models"""

    def __init__(self, model_name: str = "qwen2.5:7b"):
        import requests

        self.model_name = model_name
        self.base_url = "http://localhost:11434"

        # Verify connection
        response = requests.get(f"{self.base_url}/api/tags")
        if response.status_code != 200:
            raise ConnectionError("Ollama not running. Start with: ollama serve")

        print(f"[Ollama] Model: {model_name}")

    def generate(self, prompt: str, max_tokens: int = 1000) -> str:
        import requests

        response = requests.post(
            f"{self.base_url}/api/generate",
            json={
                "model": self.model_name,
                "prompt": prompt,
                "stream": False,
                "options": {
                    "temperature": 0.85,
                    "top_p": 0.92,
                    "num_predict": max_tokens
                }
            },
            timeout=300
        )

        return response.json()["response"]

OpenAI Generator (Cloud)

class OpenAIGenerator:
    """Generate text using OpenAI API"""

    def __init__(self, model: str = "gpt-4"):
        from openai import OpenAI
        import os

        self.client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
        self.model = model
        print(f"[OpenAI] Model: {model}")

    def generate(self, prompt: str, max_tokens: int = 1000) -> str:
        response = self.client.chat.completions.create(
            model=self.model,
            messages=[{"role": "user", "content": prompt}],
            max_tokens=max_tokens,
            temperature=0.85
        )

        return response.choices[0].message.content

Step 3: The Augmented Prompt

This is where RAG magic happens. We inject retrieved passages as style examples:

STYLE_PROMPT_TEMPLATE = """Here are some example passages showing the writing style to follow:

{context}

---

Now write a NEW story passage in a similar style.
Story idea: {user_request}

Story:
"""

Why This Works

The LLM receives:

Style examples - Shows how to write (vocabulary, pacing, tone)
Clear instruction - Write something NEW, not copy
User's idea - The creative direction

The model mimics the style while generating original content.

Step 4: The Story Generator

Putting it all together:

class StoryGenerator:
    """Generate stories using RAG + LLM"""

    def __init__(self, backend: str = "ollama", model: str = None):
        # Initialize retriever
        self.retriever = StyleRetriever()

        # Initialize generator
        if backend == "ollama":
            self.generator = OllamaGenerator(model or "qwen2.5:7b")
        elif backend == "openai":
            self.generator = OpenAIGenerator(model or "gpt-4")
        else:
            raise ValueError(f"Unknown backend: {backend}")

    def generate(self, user_request: str, n_style_samples: int = 3) -> str:
        """Generate a story with learned style"""

        # Step 1: Retrieve style samples
        print("[RAG] Retrieving style samples...")
        style_samples = self.retriever.retrieve(
            user_request,
            n_results=n_style_samples
        )

        # Step 2: Build augmented prompt
        context = "\n\n---\n\n".join(style_samples)
        prompt = STYLE_PROMPT_TEMPLATE.format(
            context=context,
            user_request=user_request
        )

        # Step 3: Generate
        print("[LLM] Generating story...")
        story = self.generator.generate(prompt)

        return story

Usage

generator = StoryGenerator(backend="ollama", model="qwen2.5:7b")

story = generator.generate(
    "A young cultivator discovers a mysterious cave behind a waterfall"
)

print(story)

Output:

Chen Wei had wandered these mountains for three days, following the
whispers of his jade pendant. The ancient artifact had belonged to
his master, and now it pulsed with an urgency he couldn't ignore.

The waterfall appeared without warning—a curtain of silver crashing
into a pool of impossible clarity. But it wasn't the water that made
his cultivation base tremble. It was what lay behind it.

"Impossible," he breathed.

The cave mouth gaped like the maw of a sleeping dragon, and from within
emanated a pressure that spoke of ages long forgotten. Qi so dense it
was almost visible swirled at the entrance, forming patterns that hurt
to look upon.

His pendant grew warm against his chest. A confirmation. A warning.

Chen Wei stepped through the waterfall.

What he found inside would change the course of his cultivation forever...

Multi-Chapter Generation

For longer stories, we need to maintain consistency across chapters.

The Challenge

Chapter 1: "Chen Wei has blue eyes"
Chapter 5: "Chen Wei's brown eyes sparkled"  ← Inconsistency!

The Solution: Summaries

After each chapter, we generate a summary. This summary is included in the prompt for subsequent chapters.

┌────────────────────────────────────────────────────────────────┐
│              MULTI-CHAPTER GENERATION                          │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│  1. Generate Story Outline                                     │
│     ┌────────────────────────────────────────┐                │
│     │ Chapter 1: The Discovery               │                │
│     │ Chapter 2: The Ancient Inheritance     │                │
│     │ Chapter 3: First Breakthrough          │                │
│     │ ...                                    │                │
│     └────────────────────────────────────────┘                │
│                         │                                      │
│                         ▼                                      │
│  2. Generate Chapter 1                                         │
│     ┌────────────────────────────────────────┐                │
│     │ Context: [Style samples from RAG]      │                │
│     │ Outline: Chapter 1 summary             │                │
│     │ → Generate full chapter                │                │
│     └────────────────────────────────────────┘                │
│                         │                                      │
│                         ▼                                      │
│  3. Summarize Chapter 1                                        │
│     "Chen Wei discovered a cave containing an                  │
│      ancient cultivator's inheritance..."                      │
│                         │                                      │
│                         ▼                                      │
│  4. Generate Chapter 2                                         │
│     ┌────────────────────────────────────────┐                │
│     │ Context: [Style samples from RAG]      │                │
│     │ Previous: [Chapter 1 summary]          │  ← Key!        │
│     │ Outline: Chapter 2 summary             │                │
│     │ → Generate full chapter                │                │
│     └────────────────────────────────────────┘                │
│                         │                                      │
│                         ▼                                      │
│  5. Repeat for all chapters...                                 │
│                                                                │
└────────────────────────────────────────────────────────────────┘

Implementation

# generate_long_story.py (simplified)

class LongStoryGenerator:
    def __init__(self, backend="ollama"):
        self.base_generator = StoryGenerator(backend=backend)
        self.chapter_summaries = []

    def generate_outline(self, premise: str, num_chapters: int = 10) -> list:
        """Generate a story outline"""
        prompt = f"""Create a {num_chapters}-chapter story outline for:
{premise}

For each chapter provide:
- Title
- Summary (2-3 sentences)
- Key events
"""
        outline_text = self.base_generator.generator.generate(prompt)
        return self._parse_outline(outline_text)

    def generate_chapter(self, chapter_num: int, chapter_outline: dict) -> str:
        """Generate a single chapter with context"""

        # Build previous summary
        previous = "\n".join([
            f"Chapter {i+1}: {s}"
            for i, s in enumerate(self.chapter_summaries)
        ])

        prompt = f"""
Previous chapters summary:
{previous if previous else "This is the beginning of the story."}

---

Write Chapter {chapter_num}: {chapter_outline['title']}

Chapter outline: {chapter_outline['summary']}

Write 2500-3500 words. Include dialogue, descriptions, and character thoughts.
"""
        # Get style samples based on chapter content
        style_samples = self.base_generator.retriever.retrieve(
            chapter_outline['summary'],
            n_results=5
        )

        full_prompt = f"""Reference writing style:
{chr(10).join(style_samples)}

---

{prompt}
"""
        return self.base_generator.generator.generate(
            full_prompt,
            max_tokens=4000
        )

    def summarize_chapter(self, chapter_content: str) -> str:
        """Create a summary for context in next chapters"""
        prompt = f"""Summarize this chapter in 100-150 words:

{chapter_content}

Focus on key events and character changes.
"""
        return self.base_generator.generator.generate(prompt, max_tokens=200)

    def generate_full_story(self, premise: str, num_chapters: int = 10):
        """Generate a complete multi-chapter story"""

        # Step 1: Generate outline
        print("Generating outline...")
        outline = self.generate_outline(premise, num_chapters)

        # Step 2: Generate each chapter
        chapters = []
        for i, chapter_outline in enumerate(outline):
            print(f"Generating Chapter {i+1}/{num_chapters}...")

            # Generate chapter
            chapter = self.generate_chapter(i+1, chapter_outline)
            chapters.append(chapter)

            # Summarize for next chapter's context
            summary = self.summarize_chapter(chapter)
            self.chapter_summaries.append(summary)

            # Save progress
            self._save_chapter(i+1, chapter)

        return chapters

Usage

# Interactive mode
python generate_long_story.py --interactive

# Direct generation
python generate_long_story.py \
  --premise "A young cultivator discovers an ancient inheritance" \
  --chapters 10 \
  --genre "Xianxia"

# Resume interrupted story
python generate_long_story.py --resume story_20240101_120000

Configuration Options

Generation Settings

# config.py

GENERATION_CONFIG = {
    "max_new_tokens": 1000,     # Short stories
    "temperature": 0.85,        # Creativity level
    "top_p": 0.92,              # Sampling diversity
    "repetition_penalty": 1.15  # Reduce repetition
}

CHAPTER_GENERATION_CONFIG = {
    "max_new_tokens": 4000,     # Full chapters (~3000 words)
    "temperature": 0.85,
    "repetition_penalty": 1.18  # Higher for long text
}

Model Recommendations

Model	Best For	Notes
qwen2.5:7b	Multilingual stories	Best for Chinese/English
llama3.1:8b	English stories	Fast, good quality
gemma2:9b	Balanced	Good all-around
gpt-4	Highest quality	Cloud, costs money
claude-3-sonnet	Creative writing	Excellent prose

Quick Commands

# Generate short story (CLI)
./run.sh generate

# Generate full chapter
./run.sh chapter

# Multi-chapter story (interactive)
./run.sh story

# List all generated stories
./run.sh stories

Example Output

Here's a sample from a Xianxia story generated by the system:

Chapter 1: The Sealed Cave

The waterfall roared like a caged beast, but Chen Wei barely heard it. His attention was fixed on the jade pendant hanging from his neck—the last gift from his dying master.

"Beyond the Crying Dragon Falls," Master Liu had whispered with his final breath, "lies the inheritance I could never claim. Perhaps you, with your crippled spiritual roots, will succeed where I failed."

Chen Wei had thought the old man delirious. But now, standing before the hundred-meter cascade, he felt it. A resonance. The pendant pulsed with warmth, responding to something hidden behind the wall of water.

He stepped through.

The cave beyond defied mortal understanding. Luminescent moss clung to walls carved with formations so complex they made his eyes water. At the center, upon a throne of crystallized qi, sat a skeleton in meditation pose.

"You have come," a voice echoed in his mind. "I have waited nine thousand years for one with spiritual roots damaged enough to contain my inheritance. Normal cultivators would explode from the power. But you... you are broken in exactly the right way."

Chen Wei's crippled dantian, the shame that had haunted him for eighteen years, suddenly felt less like a curse and more like a key.

"Who are you?" he asked the skeleton.

"I am what remains of the Heavenly Demon Emperor. And you, boy, are about to become something the cultivation world has not seen in ten thousand years."

The skeleton's empty eye sockets began to glow...

Deployment Options

Our tutorial runs everything locally on your machine. Let's explore how this works and how you can extend it to a server.

Current Architecture: Local-First

┌─────────────────────────────────────────────────────────────┐
│                    YOUR LOCAL MACHINE                        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────────┐     ┌──────────────┐    ┌──────────────┐ │
│  │   Ollama     │     │   ChromaDB   │    │   Python     │ │
│  │  (LLM API)   │◀───▶│  (Vector DB) │◀──▶│   Scripts    │ │
│  │              │     │              │    │              │ │
│  │  Port 11434  │     │  ./chroma_db │    │  Flask App   │ │
│  └──────────────┘     └──────────────┘    └──────────────┘ │
│         ▲                                        ▲          │
│         │                                        │          │
│    GPU Inference                           Port 5000        │
│    (if available)                                           │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Why Local-First?

Privacy: Your books and stories never leave your machine
Free: No API costs for generation
Offline: Works without internet connection
Learning: You understand every component

Running Locally with Ollama

Ollama makes running LLMs locally trivially easy:

# Install Ollama (macOS)
brew install ollama

# Start the server
ollama serve

# Pull a model
ollama pull qwen2.5:7b
ollama pull llama3.1:8b

# Check available models
ollama list

Hardware Requirements:

Model Size	RAM Needed	GPU VRAM	Speed
3B params	8GB	4GB	Fast
7B params	16GB	8GB	Good
14B params	32GB	16GB	Slower
70B params	64GB+	40GB+	Slow

For story generation, 7B models like qwen2.5:7b offer the best balance of quality and speed.

Local ChromaDB

ChromaDB runs as an embedded database by default:

# Embedded mode (default) - no server needed
import chromadb
client = chromadb.PersistentClient(path="./chroma_db")

# Data stored in ./chroma_db/ directory
# ~100MB for 10,000 chunks

This is perfect for local development and small-to-medium datasets.

Extending to Server Deployment

Want to deploy for multiple users or remote access? Here's how:

Option 1: Docker Compose (Simplest)

# docker-compose.yml
version: '3.8'

services:
  ollama:
    image: ollama/ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama
    deploy:
      resources:
        reservations:
          devices:
            - capabilities: [gpu]

  chromadb:
    image: chromadb/chroma
    ports:
      - "8000:8000"
    volumes:
      - chroma_data:/chroma/chroma

  app:
    build: .
    ports:
      - "5000:5000"
    environment:
      - OLLAMA_HOST=http://ollama:11434
      - CHROMA_HOST=http://chromadb:8000
    depends_on:
      - ollama
      - chromadb

volumes:
  ollama_data:
  chroma_data:

Option 2: Cloud API Backend

Switch from local Ollama to cloud APIs:

# config.py

# Option A: Use Ollama (local)
LLM_BACKEND = "ollama"
OLLAMA_MODEL = "qwen2.5:7b"

# Option B: Use OpenAI
LLM_BACKEND = "openai"
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
OPENAI_MODEL = "gpt-4"

# Option C: Use Anthropic Claude
LLM_BACKEND = "anthropic"
ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")
ANTHROPIC_MODEL = "claude-3-sonnet-20240229"

# Option D: Use Google Gemini
LLM_BACKEND = "gemini"
GOOGLE_API_KEY = os.getenv("GOOGLE_API_KEY")
GEMINI_MODEL = "gemini-pro"

Option 3: Managed Vector Database

For production, consider managed vector databases:

# Pinecone (managed)
import pinecone

pinecone.init(api_key="YOUR_KEY", environment="us-east-1")
index = pinecone.Index("story-styles")

# Weaviate (self-hosted or cloud)
import weaviate

client = weaviate.Client(url="https://your-cluster.weaviate.network")

# Qdrant (self-hosted or cloud)
from qdrant_client import QdrantClient

client = QdrantClient(url="https://your-qdrant-instance.com")

Architecture Comparison

┌────────────────────────────────────────────────────────────────┐
│                    LOCAL (Tutorial)                             │
├────────────────────────────────────────────────────────────────┤
│  User → Python App → ChromaDB (file) → Ollama (local)          │
│                                                                 │
│  Pros: Free, private, offline                                   │
│  Cons: Limited to your hardware                                 │
└────────────────────────────────────────────────────────────────┘

┌────────────────────────────────────────────────────────────────┐
│                    SERVER (Docker)                              │
├────────────────────────────────────────────────────────────────┤
│  Users → Flask App → ChromaDB Server → Ollama (GPU server)     │
│                                                                 │
│  Pros: Multiple users, better GPU                               │
│  Cons: Server costs, network latency                            │
└────────────────────────────────────────────────────────────────┘

┌────────────────────────────────────────────────────────────────┐
│                    CLOUD (Production)                           │
├────────────────────────────────────────────────────────────────┤
│  Users → Web App → Pinecone (managed) → OpenAI/Claude API      │
│                                                                 │
│  Pros: Scalable, no maintenance, best models                    │
│  Cons: API costs, data leaves your control                      │
└────────────────────────────────────────────────────────────────┘

Summary

In this series, we built a complete RAG-powered story generator:

Part 1: Understanding RAG

What RAG is and why it matters
Architecture overview
Key components (embeddings, vector DB, retrieval)
Comparison with alternatives (fine-tuning, prompt engineering)

Part 2: Building the Pipeline

Parsing ebooks (PDF, EPUB, MOBI)
Text chunking strategies
Generating embeddings
Storing in ChromaDB

Part 3: Story Generation

Connecting to LLMs (Ollama, OpenAI)
Building augmented prompts
Multi-chapter generation with summaries
Deployment options (local → server → cloud)

What's Next? Advanced RAG Features

Now that you understand the basics, here are the next features to learn and implement:

1. Hybrid Search (BM25 + Semantic)

Problem: Semantic search sometimes misses exact keyword matches.

Solution: Combine keyword search (BM25) with vector search:

from rank_bm25 import BM25Okapi

class HybridRetriever:
    def __init__(self, chunks, embeddings):
        # BM25 for keyword matching
        tokenized = [c.split() for c in chunks]
        self.bm25 = BM25Okapi(tokenized)

        # Vector search for semantic
        self.vector_store = chromadb.Client()

    def search(self, query, alpha=0.5):
        # Get BM25 scores
        bm25_scores = self.bm25.get_scores(query.split())

        # Get vector similarity scores
        vector_results = self.collection.query(query)

        # Combine with weighted average
        final_scores = alpha * bm25_scores + (1-alpha) * vector_scores
        return ranked_results

When to use: When users search for specific character names, locations, or technical terms.

2. Query Expansion

Problem: User query may not match document vocabulary.

Solution: Expand query with synonyms or LLM-generated variations:

def expand_query(self, query: str) -> list[str]:
    """Generate query variations"""
    prompt = f"""Generate 3 alternative phrasings for this search:
    "{query}"

    List only the alternatives, one per line."""

    variations = self.llm.generate(prompt)
    return [query] + variations.split('\n')

3. Cross-Encoder Reranking

Problem: Bi-encoder embeddings miss nuanced relevance.

Solution: Use a cross-encoder to rerank top results:

from sentence_transformers import CrossEncoder

class RerankedRetriever:
    def __init__(self):
        self.retriever = StyleRetriever()
        self.reranker = CrossEncoder('cross-encoder/ms-marco-MiniLM-L-6-v2')

    def retrieve(self, query: str, n_results: int = 5):
        # First pass: get top 20 candidates
        candidates = self.retriever.retrieve(query, n_results=20)

        # Second pass: rerank with cross-encoder
        pairs = [[query, doc] for doc in candidates]
        scores = self.reranker.predict(pairs)

        # Return top N after reranking
        ranked = sorted(zip(candidates, scores), key=lambda x: x[1], reverse=True)
        return [doc for doc, score in ranked[:n_results]]

Why it works: Cross-encoders see query and document together, understanding their relationship better.

4. Semantic Chunking

Problem: Fixed-size chunks cut sentences and paragraphs awkwardly.

Solution: Chunk by semantic boundaries:

def semantic_chunk(text: str, max_size: int = 1000):
    """Split at paragraph/scene boundaries"""
    # Split by paragraph
    paragraphs = text.split('\n\n')

    chunks = []
    current_chunk = ""

    for para in paragraphs:
        # Check if adding this paragraph exceeds limit
        if len(current_chunk) + len(para) > max_size:
            if current_chunk:
                chunks.append(current_chunk.strip())
            current_chunk = para
        else:
            current_chunk += "\n\n" + para

    if current_chunk:
        chunks.append(current_chunk.strip())

    return chunks

Advanced: Use an LLM to identify natural break points (scene changes, topic shifts).

5. Metadata Filtering

Problem: All chunks are treated equally regardless of source.

Solution: Add and filter by metadata:

# When building the database
collection.add(
    documents=[chunk],
    embeddings=[embedding],
    metadatas=[{
        "source_file": "cultivation_novel_1.txt",
        "author": "Unknown",
        "genre": "xianxia",
        "chapter": 5,
        "word_count": len(chunk.split())
    }],
    ids=[chunk_id]
)

# When querying
results = collection.query(
    query_embeddings=[query_embedding],
    n_results=5,
    where={
        "genre": "xianxia",
        "word_count": {"$gt": 200}
    }
)

6. Caching for Performance

Problem: Re-embedding the same queries wastes compute.

Solution: Cache embeddings and results:

from functools import lru_cache
import hashlib

class CachedRetriever:
    def __init__(self):
        self.retriever = StyleRetriever()
        self._cache = {}

    def retrieve(self, query: str, n_results: int = 5):
        # Create cache key
        cache_key = hashlib.md5(f"{query}:{n_results}".encode()).hexdigest()

        if cache_key in self._cache:
            return self._cache[cache_key]

        results = self.retriever.retrieve(query, n_results)
        self._cache[cache_key] = results
        return results

7. Evaluation Metrics

Problem: How do you know if retrieval is actually working?

Solution: Implement evaluation metrics:

def evaluate_retrieval(test_queries: list, ground_truth: dict):
    """
    Measure retrieval quality

    Args:
        test_queries: List of test queries
        ground_truth: {query: [relevant_doc_ids]}
    """
    retriever = StyleRetriever()

    metrics = {
        "precision@5": [],
        "recall@5": [],
        "mrr": []  # Mean Reciprocal Rank
    }

    for query in test_queries:
        results = retriever.retrieve(query, n_results=5)
        relevant = ground_truth[query]

        # Calculate precision@5
        retrieved_ids = [r['id'] for r in results]
        hits = len(set(retrieved_ids) & set(relevant))
        metrics["precision@5"].append(hits / 5)
        metrics["recall@5"].append(hits / len(relevant))

        # Calculate MRR
        for i, rid in enumerate(retrieved_ids):
            if rid in relevant:
                metrics["mrr"].append(1 / (i + 1))
                break
        else:
            metrics["mrr"].append(0)

    return {k: sum(v)/len(v) for k, v in metrics.items()}

8. Document Hierarchy

Problem: Losing context about where a chunk came from.

Solution: Store hierarchical context:

Book → Chapter → Section → Paragraph → Chunk

# Store parent context with each chunk
metadata = {
    "book_title": "Cultivation Journey",
    "chapter_number": 5,
    "chapter_title": "The Hidden Inheritance",
    "section": "discovery",
    "parent_chunk_id": "chunk_004",  # Previous chunk
    "child_chunk_ids": ["chunk_006", "chunk_007"]
}

When generating, you can include parent context for better coherence.

Learning Path

Here's a suggested order to learn these features:

1. Metadata Filtering (Easy)
   └── Add author/genre filters to your queries

2. Caching (Easy)
   └── Speed up repeated queries

3. Semantic Chunking (Medium)
   └── Better chunk quality = better retrieval

4. Hybrid Search (Medium)
   └── Combine the best of keyword + semantic

5. Cross-Encoder Reranking (Medium)
   └── Significantly improve relevance

6. Query Expansion (Medium)
   └── Handle query-document vocabulary mismatch

7. Evaluation Metrics (Advanced)
   └── Measure and improve systematically

8. Document Hierarchy (Advanced)
   └── Handle complex document structures

Production Considerations

If you're taking this to production, also consider:

Concern	Solution
Scale	Distributed vector DB (Pinecone, Weaviate)
Latency	Pre-compute embeddings, cache aggressively
Cost	Smaller models, batched requests
Quality	Evaluation pipeline, A/B testing
Security	Input sanitization, output filtering
Monitoring	Log queries, track retrieval quality

Resources

Source Code: github.com/namtran/ai-rag-tutorial-story-generator
ChromaDB Docs: docs.trychroma.com
Sentence Transformers: sbert.net
Ollama: ollama.ai

Previous Articles:

*Thanks for following this series!

Build Your Own AI Story Generator with RAG - Part 2: Building the RAG Pipeline

Nam Tran — Mon, 26 Jan 2026 01:15:09 +0000

In Part 1, we learned what RAG is, compared it to alternatives, and understood its pros, cons, and limitations. Now let's build it.

In this article, we'll create the complete data pipeline:

Ebooks → Parse → Chunk → Embed → Store in ChromaDB

By the end, you'll have a searchable vector database of writing styles ready for story generation.

Source Code: github.com/namtran/ai-rag-tutorial-story-generator

Project Setup
Step 1: Parsing Ebooks
Step 2: Text Chunking
Step 3: Generating Embeddings
Step 4: Storing in ChromaDB
Step 5: Testing Retrieval
Troubleshooting Common Issues
Performance Optimization Tips

Project Setup

Clone and Install

git clone https://github.com/namtran/ai-rag-tutorial-story-generator.git
cd ai-rag-tutorial-story-generator

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Key Dependencies Explained

# requirements.txt

# Vector Database
chromadb>=0.4.0          # Lightweight, embedded vector DB

# Embeddings
sentence-transformers    # Pre-trained embedding models

# Ebook Parsing
PyMuPDF                  # PDF text extraction (fast, reliable)
ebooklib                 # EPUB parsing
mobi                     # MOBI/PRC parsing
beautifulsoup4           # HTML cleaning for EPUB

# LLM Backends (for Part 3)
requests                 # For Ollama API
openai                   # For OpenAI API

# Web UI (for Part 3)
gradio                   # Simple web interface

Project Structure

ai-rag-tutorial-story-generator/
├── data/
│   ├── raw/              # Your ebooks go here (.pdf, .epub, .mobi, .txt)
│   └── txt/              # Parsed text files (auto-generated)
├── chroma_db/            # Vector database (auto-generated)
├── models/               # Cached embedding models
│
├── config.py             # All configuration in one place
├── parse_ebooks.py       # Step 1: Parse ebooks → text
├── build_style_db.py     # Step 2-4: Chunk → Embed → Store
├── generate_with_style.py # Step 5+: Retrieve → Generate (Part 3)
│
├── run.sh                # Quick commands
└── requirements.txt

Configuration Deep Dive

# config.py - Key settings explained

# ===== DIRECTORIES =====
BASE_DIR = Path(__file__).parent.resolve()
RAW_DIR = BASE_DIR / "data" / "raw"    # Put your ebooks here
TXT_DIR = BASE_DIR / "data" / "txt"    # Parsed text output
CHROMA_DIR = BASE_DIR / "chroma_db"    # Vector database

# ===== EMBEDDING MODEL =====
# We use a multilingual model to support books in any language
# This model outputs 384-dimensional vectors
EMBED_MODEL = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"

# Alternative models:
# "all-MiniLM-L6-v2"           # Faster, English-only, 384d
# "all-mpnet-base-v2"          # Better quality, slower, 768d
# "paraphrase-multilingual-mpnet-base-v2"  # Better multilingual, 768d

# ===== CHUNKING SETTINGS =====
RAG_CONFIG = {
    "chunk_size": 500,      # Characters per chunk
    "chunk_overlap": 50,    # Overlap between chunks
    "min_chunk_length": 100 # Skip chunks smaller than this
}

# Why these values?
# - 500 chars ≈ 100 words ≈ 1-2 paragraphs
# - Large enough for context, small enough for precise retrieval
# - 50 char overlap prevents losing info at boundaries
# - 10% overlap is a good balance (not too much redundancy)

# ===== COLLECTION NAME =====
COLLECTION_NAME = "story_styles"  # Name in ChromaDB

Step 1: Parsing Ebooks

The Challenge

Ebooks come in many formats, each with its own structure:

Format	Structure	Challenge
PDF	Fixed layout, pages	May have headers/footers, columns
EPUB	HTML/CSS in a ZIP	Need to extract from HTML
MOBI/PRC	Amazon proprietary	Need special library
TXT	Plain text	Encoding issues

Understanding the Parser Code

# parse_ebooks.py - Complete with explanations

from pathlib import Path
import fitz  # PyMuPDF - Note the import name!
import ebooklib
from ebooklib import epub
from bs4 import BeautifulSoup
import mobi

def parse_pdf(file_path: Path) -> str:
    """
    Extract text from PDF files.

    Uses PyMuPDF (fitz) which is fast and handles most PDFs well.
    Preserves paragraph structure by keeping line breaks.
    """
    doc = fitz.open(file_path)
    text_parts = []

    for page_num, page in enumerate(doc):
        # Extract text with layout preservation
        text = page.get_text("text")

        # Optional: Skip first/last pages (often cover/copyright)
        # if page_num == 0 or page_num == len(doc) - 1:
        #     continue

        text_parts.append(text)

    doc.close()

    # Join with double newline to preserve page breaks
    full_text = "\n\n".join(text_parts)

    # Clean up excessive whitespace
    import re
    full_text = re.sub(r'\n{3,}', '\n\n', full_text)

    return full_text


def parse_epub(file_path: Path) -> str:
    """
    Extract text from EPUB files.

    EPUB files are basically ZIP files containing HTML.
    We extract text from each HTML document in reading order.
    """
    book = epub.read_epub(str(file_path))
    text_parts = []

    # Get items in reading order
    for item in book.get_items():
        # Only process document items (not images, CSS, etc.)
        if item.get_type() == ebooklib.ITEM_DOCUMENT:
            # Parse HTML content
            soup = BeautifulSoup(item.get_content(), 'html.parser')

            # Remove script and style elements
            for element in soup(['script', 'style', 'nav']):
                element.decompose()

            # Get text
            text = soup.get_text(separator='\n')
            text_parts.append(text)

    full_text = "\n\n".join(text_parts)

    # Clean up
    import re
    full_text = re.sub(r'\n{3,}', '\n\n', full_text)
    full_text = re.sub(r' {2,}', ' ', full_text)

    return full_text


def parse_mobi(file_path: Path) -> str:
    """
    Extract text from MOBI/PRC files (Kindle format).

    These files are more complex - we extract to temp directory
    then parse the resulting HTML.
    """
    import tempfile
    import os

    with tempfile.TemporaryDirectory() as temp_dir:
        # Extract MOBI to temp directory
        temp_path, _ = mobi.extract(str(file_path))

        # Find the HTML file
        html_file = None
        for root, dirs, files in os.walk(temp_path):
            for file in files:
                if file.endswith('.html'):
                    html_file = os.path.join(root, file)
                    break

        if html_file:
            with open(html_file, 'r', encoding='utf-8', errors='ignore') as f:
                soup = BeautifulSoup(f.read(), 'html.parser')
                text = soup.get_text(separator='\n')
        else:
            # Fallback: try to read as text
            with open(temp_path, 'r', encoding='utf-8', errors='ignore') as f:
                text = f.read()

    return text


def parse_txt(file_path: Path) -> str:
    """
    Read plain text files.

    Handle various encodings gracefully.
    """
    encodings = ['utf-8', 'latin-1', 'cp1252', 'ascii']

    for encoding in encodings:
        try:
            return file_path.read_text(encoding=encoding)
        except UnicodeDecodeError:
            continue

    # Last resort: ignore errors
    return file_path.read_text(encoding='utf-8', errors='ignore')


def parse_ebook(file_path: Path) -> str:
    """
    Parse any supported ebook format.

    Returns cleaned text ready for chunking.
    """
    suffix = file_path.suffix.lower()

    parsers = {
        '.pdf': parse_pdf,
        '.epub': parse_epub,
        '.mobi': parse_mobi,
        '.prc': parse_mobi,  # PRC is same as MOBI
        '.txt': parse_txt,
    }

    if suffix not in parsers:
        raise ValueError(f"Unsupported format: {suffix}")

    return parsers[suffix](file_path)


def clean_text(text: str) -> str:
    """
    Clean and normalize extracted text.

    - Remove excessive whitespace
    - Fix common OCR errors
    - Normalize quotes and dashes
    """
    import re

    # Normalize line endings
    text = text.replace('\r\n', '\n').replace('\r', '\n')

    # Remove excessive blank lines
    text = re.sub(r'\n{3,}', '\n\n', text)

    # Remove excessive spaces
    text = re.sub(r' {2,}', ' ', text)

    # Fix common issues
    text = text.replace('"', '"').replace('"', '"')  # Smart quotes
    text = text.replace(''', "'").replace(''', "'")  # Smart apostrophes
    text = text.replace('—', '--').replace('–', '-')  # Dashes

    # Remove page numbers (common pattern)
    text = re.sub(r'\n\d+\n', '\n', text)

    # Strip leading/trailing whitespace from lines
    lines = [line.strip() for line in text.split('\n')]
    text = '\n'.join(lines)

    return text.strip()

Running the Parser

# Add your ebooks
cp ~/Books/*.epub data/raw/
cp ~/Books/*.pdf data/raw/

# Run parser
python parse_ebooks.py

Expected Output:

============================================================
EBOOK PARSER
============================================================
Source: data/raw/
Output: data/txt/
============================================================

[PARSE] Found 5 ebooks to process

[1/5] fantasy_novel.epub
      Format: EPUB
      Processing... Done!
      Output: fantasy_novel.txt (245,832 characters)

[2/5] cultivation_story.pdf
      Format: PDF (127 pages)
      Processing... Done!
      Output: cultivation_story.txt (523,109 characters)

[3/5] magic_school.mobi
      Format: MOBI
      Processing... Done!
      Output: magic_school.txt (312,445 characters)

...

============================================================
COMPLETE
============================================================
Processed: 5 files
Total text: 1,523,891 characters
Output directory: data/txt/
============================================================

Step 2: Text Chunking

Why Chunking Matters

Chunking is critical for RAG quality. Bad chunking = bad retrieval = bad output.

┌─────────────────────────────────────────────────────────────────┐
│                    CHUNKING IMPACT                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  User Query: "Write about a warrior's first battle"            │
│                                                                 │
│  GOOD CHUNKING:                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ "Chen Wei gripped his sword tightly, knuckles white.    │   │
│  │ Before him stood a hundred enemy soldiers. This was it  │   │
│  │ - his first real battle. Master Liu's training echoed   │   │
│  │ in his mind: 'When fear comes, let it pass through you.'│   │
│  │ He raised his blade and charged."                       │   │
│  └─────────────────────────────────────────────────────────┘   │
│  → Complete scene, good context, useful for style learning     │
│                                                                 │
│  BAD CHUNKING:                                                  │
│  ┌──────────────────────┐ ┌──────────────────────────────────┐ │
│  │ "Chen Wei gripped his│ │sword tightly, knuckles white.   │ │
│  │"                     │ │Before him stood a hundred enemy │ │
│  └──────────────────────┘ └──────────────────────────────────┘ │
│  → Split mid-sentence, loses meaning, poor retrieval           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Chunking Strategies Compared

Strategy	How It Works	Pros	Cons	Best For
Fixed-size	Every N characters	Simple, predictable	May cut mid-sentence	General use
Sentence	Split on periods	Natural boundaries	Variable sizes	Precise retrieval
Paragraph	Split on newlines	Preserves ideas	Very variable	Long-form content
Semantic	ML-based topic detection	Best relevance	Slow, complex	Production systems
Recursive	Try large, then smaller	Adaptive	More complex	Mixed content

Our Implementation: Fixed-Size with Smart Boundaries

# From build_style_db.py

def chunk_text(
    text: str,
    chunk_size: int = 500,
    overlap: int = 50,
    min_length: int = 100
) -> list[str]:
    """
    Split text into overlapping chunks with smart boundary detection.

    Args:
        text: Full text to chunk
        chunk_size: Target size in characters
        overlap: Characters to overlap between chunks
        min_length: Minimum chunk size (skip smaller)

    Returns:
        List of text chunks
    """
    chunks = []
    start = 0
    text_length = len(text)

    while start < text_length:
        # Get initial chunk
        end = start + chunk_size

        # Don't go past the end
        if end >= text_length:
            chunk = text[start:].strip()
            if len(chunk) >= min_length:
                chunks.append(chunk)
            break

        # Extract chunk
        chunk = text[start:end]

        # Find the best break point (sentence boundary)
        # Look for period, exclamation, or question mark followed by space
        best_break = -1

        for punct in ['. ', '! ', '? ', '.\n', '!\n', '?\n']:
            pos = chunk.rfind(punct)
            if pos > best_break and pos > chunk_size * 0.5:
                best_break = pos + len(punct)

        # If found a good break point, use it
        if best_break > 0:
            chunk = chunk[:best_break].strip()
            end = start + best_break

        # Also try paragraph break
        para_break = chunk.rfind('\n\n')
        if para_break > chunk_size * 0.7:  # Prefer paragraph if late enough
            chunk = chunk[:para_break].strip()
            end = start + para_break

        # Add chunk if long enough
        if len(chunk) >= min_length:
            chunks.append(chunk)

        # Move start, accounting for overlap
        start = end - overlap if end > overlap else end

    return chunks

Visualizing Overlap

Original text (simplified):
"AAAAAAAAAA BBBBBBBBBB CCCCCCCCCC DDDDDDDDDD EEEEEEEEEE"
 |-------- chunk 1 --------|
              |-------- chunk 2 --------|
                           |-------- chunk 3 --------|

Chunk 1: "AAAAAAAAAA BBBBBBBBBB CC"
Chunk 2: "BB CCCCCCCCCC DDDDDDDDDD"  ← "BB CC" appears in both!
Chunk 3: "DD EEEEEEEEEE"

Why overlap?
- Sentence about "B and C" isn't lost at boundary
- Queries about "C" can match chunks 1 or 2
- Better retrieval for edge cases

Testing Your Chunks

# test_chunking.py - Verify chunk quality

from build_style_db import chunk_text

# Load a sample text
with open("data/txt/sample_book.txt") as f:
    text = f.read()

# Chunk it
chunks = chunk_text(text, chunk_size=500, overlap=50)

# Analyze
print(f"Total chunks: {len(chunks)}")
print(f"Avg chunk size: {sum(len(c) for c in chunks) / len(chunks):.0f} chars")
print(f"Min chunk size: {min(len(c) for c in chunks)} chars")
print(f"Max chunk size: {max(len(c) for c in chunks)} chars")

# Show a few samples
print("\n--- Sample Chunks ---")
for i in [0, len(chunks)//2, -1]:
    print(f"\nChunk {i}:")
    print(chunks[i][:200] + "...")
    print(f"Length: {len(chunks[i])} chars")

Step 3: Generating Embeddings

What Are Embeddings?

Embeddings convert text into dense vectors that capture semantic meaning:

from sentence_transformers import SentenceTransformer

model = SentenceTransformer('paraphrase-multilingual-MiniLM-L12-v2')

# Text becomes a vector
text = "The warrior drew his sword"
vector = model.encode(text)

print(f"Text: '{text}'")
print(f"Vector shape: {vector.shape}")  # (384,)
print(f"First 5 values: {vector[:5]}")  # [0.23, -0.45, 0.67, ...]

Why Embeddings Work

Semantic similarity is captured in vector space:

"The warrior drew his sword"     →  [0.23, -0.45, 0.67, ...]
"The fighter unsheathed blade"   →  [0.21, -0.43, 0.65, ...]  ← Similar!
"I like to eat pizza"            →  [-0.56, 0.32, -0.11, ...] ← Different!

                    sword/blade
                         ↑
                    [warrior] [fighter]
                         |
    pizza →  [ ]         |
                         |
                    word embedding space

Choosing an Embedding Model

Model	Dimensions	Speed	Quality	Languages	Size
all-MiniLM-L6-v2	384	Very Fast	Good	English	80MB
all-MiniLM-L12-v2	384	Fast	Better	English	120MB
paraphrase-multilingual-MiniLM-L12-v2	384	Fast	Good	50+	420MB
all-mpnet-base-v2	768	Medium	Best	English	420MB
paraphrase-multilingual-mpnet-base-v2	768	Medium	Best	50+	970MB

We use paraphrase-multilingual-MiniLM-L12-v2 because:

Supports 50+ languages (Chinese, Vietnamese, etc.)
Good balance of speed and quality
384 dimensions is efficient for storage
Works well for style/semantic similarity

Embedding Implementation

# From build_style_db.py

from sentence_transformers import SentenceTransformer
from tqdm import tqdm

class EmbeddingGenerator:
    def __init__(self, model_name: str = EMBED_MODEL):
        print(f"[EMBED] Loading model: {model_name}")
        self.model = SentenceTransformer(model_name)
        print(f"[EMBED] Model loaded! Dimension: {self.model.get_sentence_embedding_dimension()}")

    def embed_chunks(self, chunks: list[str], batch_size: int = 32) -> list:
        """
        Generate embeddings for a list of text chunks.

        Uses batching for efficiency on large datasets.
        Shows progress bar for long operations.
        """
        print(f"[EMBED] Generating embeddings for {len(chunks)} chunks...")

        # For small datasets, encode all at once
        if len(chunks) <= batch_size:
            embeddings = self.model.encode(chunks, show_progress_bar=True)
            return embeddings.tolist()

        # For large datasets, batch for memory efficiency
        all_embeddings = []

        for i in tqdm(range(0, len(chunks), batch_size), desc="Embedding"):
            batch = chunks[i:i + batch_size]
            batch_embeddings = self.model.encode(batch)
            all_embeddings.extend(batch_embeddings.tolist())

        return all_embeddings

    def embed_query(self, query: str) -> list:
        """Embed a single query string."""
        return self.model.encode(query).tolist()

Embedding Performance Tips

# Speed comparison for 10,000 chunks:

# CPU (Intel i7)
# - batch_size=32:  ~5 minutes
# - batch_size=64:  ~4 minutes
# - batch_size=128: ~3.5 minutes (may OOM on 8GB RAM)

# GPU (NVIDIA RTX 3080)
# - batch_size=32:  ~30 seconds
# - batch_size=64:  ~20 seconds
# - batch_size=128: ~15 seconds

# Apple Silicon (M1/M2)
# - batch_size=32:  ~2 minutes
# - batch_size=64:  ~1.5 minutes

# Tip: For large collections, run overnight!

Step 4: Storing in ChromaDB

Why ChromaDB?

Feature	ChromaDB	Pinecone	Weaviate	Milvus
Deployment	Embedded	Cloud	Self-hosted	Self-hosted
Setup	pip install	Account required	Docker	Docker/K8s
Cost	Free	Free tier + paid	Free	Free
Scale	~1M vectors	Billions	Billions	Billions
Best For	Learning, prototypes	Production	Production	Enterprise

ChromaDB is perfect for learning because:

No server to run
Data persists to disk
Simple Python API
Works offline

Creating the Database

# From build_style_db.py

import chromadb
from chromadb.config import Settings

def create_database(db_path: str, collection_name: str):
    """
    Create or connect to a ChromaDB database.

    Args:
        db_path: Directory to store database files
        collection_name: Name for the collection

    Returns:
        ChromaDB collection object
    """
    # Create persistent client (data survives restarts)
    client = chromadb.PersistentClient(
        path=db_path,
        settings=Settings(
            anonymized_telemetry=False  # Disable telemetry
        )
    )

    # Delete existing collection if present (for clean rebuild)
    try:
        client.delete_collection(collection_name)
        print(f"[DB] Deleted existing collection: {collection_name}")
    except ValueError:
        pass  # Collection didn't exist

    # Create new collection
    collection = client.create_collection(
        name=collection_name,
        metadata={
            "description": "Writing style samples for story generation",
            "hnsw:space": "cosine"  # Use cosine similarity
        }
    )

    print(f"[DB] Created collection: {collection_name}")
    return collection

Adding Documents

def add_to_database(
    collection,
    chunks: list[str],
    embeddings: list[list[float]],
    source_file: str
):
    """
    Add chunks and embeddings to ChromaDB.

    Args:
        collection: ChromaDB collection
        chunks: List of text chunks
        embeddings: Corresponding embeddings
        source_file: Name of source file (for metadata)
    """
    # Generate unique IDs
    # Format: source_chunknum (e.g., "fantasy_novel_0042")
    base_name = Path(source_file).stem
    ids = [f"{base_name}_{i:04d}" for i in range(len(chunks))]

    # Create metadata for each chunk
    metadatas = [
        {
            "source": source_file,
            "chunk_index": i,
            "char_count": len(chunk)
        }
        for i, chunk in enumerate(chunks)
    ]

    # Add to collection
    # ChromaDB handles batching internally
    collection.add(
        ids=ids,
        documents=chunks,
        embeddings=embeddings,
        metadatas=metadatas
    )

    print(f"[DB] Added {len(chunks)} chunks from {source_file}")

The Complete Build Script

# build_style_db.py - Complete pipeline

def build_database():
    """Build the complete vector database from parsed texts."""

    print("=" * 60)
    print("BUILDING STYLE DATABASE")
    print("=" * 60)

    # Initialize components
    embedder = EmbeddingGenerator()
    collection = create_database(str(CHROMA_DIR), COLLECTION_NAME)

    # Track statistics
    total_chunks = 0
    total_chars = 0

    # Process each text file
    txt_files = list(TXT_DIR.glob("*.txt"))
    print(f"\nFound {len(txt_files)} text files to process\n")

    for txt_file in txt_files:
        print(f"[PROCESS] {txt_file.name}")

        # Read text
        text = txt_file.read_text(encoding='utf-8')
        print(f"  Characters: {len(text):,}")

        # Chunk
        chunks = chunk_text(
            text,
            chunk_size=RAG_CONFIG["chunk_size"],
            overlap=RAG_CONFIG["chunk_overlap"],
            min_length=RAG_CONFIG["min_chunk_length"]
        )
        print(f"  Chunks: {len(chunks)}")

        # Embed
        embeddings = embedder.embed_chunks(chunks)

        # Store
        add_to_database(collection, chunks, embeddings, txt_file.name)

        # Update stats
        total_chunks += len(chunks)
        total_chars += len(text)

        print()

    # Final summary
    print("=" * 60)
    print("BUILD COMPLETE")
    print("=" * 60)
    print(f"Total text processed: {total_chars:,} characters")
    print(f"Total chunks created: {total_chunks:,}")
    print(f"Database location: {CHROMA_DIR}")
    print(f"Collection: {COLLECTION_NAME}")
    print("=" * 60)


if __name__ == "__main__":
    build_database()

Running the Build

python build_style_db.py

Expected Output:

============================================================
BUILDING STYLE DATABASE
============================================================
[EMBED] Loading model: sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
[EMBED] Model loaded! Dimension: 384
[DB] Created collection: story_styles

Found 5 text files to process

[PROCESS] fantasy_novel.txt
  Characters: 245,832
  Chunks: 523
  Embedding: 100%|████████████████████| 17/17 [00:08<00:00]
  [DB] Added 523 chunks from fantasy_novel.txt

[PROCESS] cultivation_story.txt
  Characters: 523,109
  Chunks: 1,112
  Embedding: 100%|████████████████████| 35/35 [00:17<00:00]
  [DB] Added 1,112 chunks from cultivation_story.txt

...

============================================================
BUILD COMPLETE
============================================================
Total text processed: 1,523,891 characters
Total chunks created: 3,247
Database location: chroma_db/
Collection: story_styles
============================================================

Step 5: Testing Retrieval

Basic Retrieval Test

# test_retrieval.py

import chromadb
from sentence_transformers import SentenceTransformer
from config import CHROMA_DIR, EMBED_MODEL, COLLECTION_NAME

# Connect to database
client = chromadb.PersistentClient(path=str(CHROMA_DIR))
collection = client.get_collection(COLLECTION_NAME)

# Load embedding model
embedder = SentenceTransformer(EMBED_MODEL)

# Test queries
test_queries = [
    "A young warrior discovers a magical sword",
    "The cultivation technique for immortality",
    "A magic school hidden from ordinary people",
    "A dark lord threatens the kingdom",
]

for query in test_queries:
    print(f"\n{'='*60}")
    print(f"Query: {query}")
    print('='*60)

    # Embed query
    query_embedding = embedder.encode(query).tolist()

    # Search
    results = collection.query(
        query_embeddings=[query_embedding],
        n_results=3,
        include=["documents", "distances", "metadatas"]
    )

    # Display results
    for i, (doc, dist, meta) in enumerate(zip(
        results['documents'][0],
        results['distances'][0],
        results['metadatas'][0]
    )):
        print(f"\n--- Result {i+1} (distance: {dist:.4f}) ---")
        print(f"Source: {meta['source']}")
        print(f"Preview: {doc[:200]}...")

Understanding Distance Scores

ChromaDB returns distance, not similarity. Lower = more similar.

Distance interpretation (cosine):
0.0 - 0.3  : Very relevant (almost identical meaning)
0.3 - 0.5  : Relevant (similar topic)
0.5 - 0.7  : Somewhat relevant (related)
0.7 - 1.0  : Not very relevant
1.0+       : Unrelated

What Good Retrieval Looks Like

Query: "A young warrior discovers a magical sword"

--- Result 1 (distance: 0.2341) ---
Source: xianxia_novel.txt
Preview: "Chen Wei's fingers closed around the hilt, and ancient
power surged through his meridians. The sword had chosen him.
After ten thousand years, the Heavenly Demon Blade had found
a new master..."

--- Result 2 (distance: 0.2876) ---
Source: fantasy_epic.txt
Preview: "The blade sang as it left the stone, a sound that had
not been heard in seven generations. Young Thomas stared at
his own hands in disbelief. He had done what kings and warriors
could not..."

--- Result 3 (distance: 0.3102) ---
Source: cultivation_story.txt
Preview: "Master Liu held out the rusted sword. 'This weapon chose
your ancestor,' he said. 'Now it stirs again. Take it, if you
dare face the trials that come with such power...'"

All three results are about discovering magical swords!

Troubleshooting Common Issues

Issue 1: "Collection not found" Error

# Error: ValueError: Collection story_styles does not exist.

# Solution: Build the database first!
python build_style_db.py

# Or with reset flag:
python build_style_db.py --reset

Issue 2: Poor Retrieval Quality

Symptom: Retrieved passages don't match query

Causes and solutions:
1. Too few source documents
   → Add more ebooks to data/raw/

2. Chunks too small
   → Increase chunk_size in config.py

3. Wrong embedding model for language
   → Use multilingual model for non-English

4. Query too vague
   → Make queries more specific

Issue 3: Out of Memory During Embedding

Symptom: MemoryError or process killed

Solutions:
1. Reduce batch_size in embed_chunks()
2. Process fewer books at once
3. Use a smaller embedding model
4. Add more RAM (16GB+ recommended)

Issue 4: Slow Embedding Speed

Symptom: Takes hours to embed

Solutions:
1. Use GPU if available:
   pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

2. Use smaller model:
   EMBED_MODEL = "all-MiniLM-L6-v2"  # 2x faster

3. Increase batch_size if you have enough RAM

Performance Optimization Tips

1. Optimal Chunk Sizes by Use Case

Use Case	Chunk Size	Overlap	Why
Short stories	300-400	30	Tighter focus
Novels	500-600	50	Balance
Technical docs	400-500	50	Preserve sections
Poetry	200-300	20	Keep stanzas

2. When to Rebuild vs. Add

# ADD new documents (fast):
# When: Adding a few new books
# How: Run build_style_db.py with --add flag (if implemented)
#      Or manually add to existing collection

# REBUILD entire database:
# When: Changed chunk_size, changed embedding model, major changes
# How: Delete chroma_db/ and run build_style_db.py fresh

3. Database Size Estimates

Rule of thumb:
- 1 ebook ≈ 500 chunks
- 500 chunks × 384 dimensions × 4 bytes = ~750 KB embeddings
- Plus text storage ≈ 500 KB
- Total per book ≈ 1.5 MB

For 100 books: ~150 MB database
For 1000 books: ~1.5 GB database

Summary

In this article, we built:

Component	Purpose	Key Files
Ebook Parser	Extract text from PDF, EPUB, MOBI, TXT	parse_ebooks.py
Text Chunker	Split into overlapping chunks	build_style_db.py
Embedding Generator	Convert text to vectors	build_style_db.py
Vector Database	Store and search embeddings	chroma_db/

Our RAG data pipeline is complete. In Part 3, we'll connect this to LLMs and generate stories that match our learned writing styles.

Quick Reference

# Parse ebooks
./run.sh parse
# or
python parse_ebooks.py

# Build vector database
./run.sh build
# or
python build_style_db.py

# Check status
./run.sh status

# Test retrieval
python -c "
from test_retrieval import test_query
test_query('warrior discovers sword')
"

Next Article: Part 3: Story Generation with RAG →

Previous: Part 1: Understanding RAG

Source Code: github.com/namtran/ai-rag-tutorial-story-generator

Build Your Own AI Story Generator with RAG - Part 1: Understanding RAG

Nam Tran — Mon, 26 Jan 2026 01:04:25 +0000

Learn what RAG is, why we choose it over fine-tuning and other alternatives, with detailed comparisons, pros/cons, and current limitations.

Have you ever wanted an AI to write stories in your favorite author's style? Or wished ChatGPT knew about your company's internal documents?

That's exactly what RAG (Retrieval-Augmented Generation) enables.

In this 3-part tutorial series, we'll build a complete AI story generator that learns writing styles from your ebook collection. By the end, you'll understand RAG deeply—not just theoretically, but through hands-on implementation.

What we're building:

A system that learns writing styles from any ebook collection
Multi-chapter story generation with consistency
Support for multiple LLM backends (Ollama, OpenAI, Claude)

Source Code: github.com/namtran/ai-rag-tutorial-story-generator

The Problem: LLMs Don't Know Your Data
Methods to Add Custom Knowledge
Deep Dive: RAG Pros and Cons
Current Limitations of RAG
Why We Choose RAG for This Project
How RAG Actually Works
Our Architecture

The Problem: LLMs Don't Know Your Data

Large Language Models like GPT-4, Claude, and Llama are trained on massive datasets from the internet. They're incredibly capable, but they have fundamental limitations:

1. Knowledge Cutoff

Models only know information up to their training date.

You: "What happened in the 2024 Olympics?"
GPT-4: "I don't have information about events after April 2024..."

More importantly for us: LLMs don't know about your personal book collection, your company documents, or any private data.

2. Generic Responses

Ask an LLM to write a story, and you'll get competent but generic prose:

Prompt: "Write about a cultivator discovering a cave"

Generic LLM Response:
"The young man walked into the cave. It was dark and mysterious.
He felt a strange energy. Something powerful was hidden here..."

What we want (Xianxia style):
"Chen Wei's spiritual sense trembled as he pushed through the
waterfall. Ancient qi, dense enough to manifest as mist, swirled
within the cave mouth. His dantian resonated with a frequency
he had only read about in the Celestial Archives—the signature
of a Nascent Soul realm cultivator's inheritance..."

3. Hallucinations

Without access to source material, LLMs confidently generate plausible-sounding but incorrect information:

You: "What does Chapter 7 of my company handbook say about vacation policy?"
LLM: "According to your handbook, employees receive 15 days..."
     (completely made up - it has no access to your handbook!)

4. No Personalization

Everyone gets the same model. A fantasy author and a technical writer get identical responses to the same prompt. There's no way to customize the model to your specific domain without significant effort.

5. Context Window Limitations

Even if you try to paste your entire book into the prompt:

Model	Context Window	Equivalent
GPT-3.5	4K tokens	~3,000 words
GPT-4	8K-128K tokens	~6,000-96,000 words
Claude 3	200K tokens	~150,000 words

A typical novel is 80,000-100,000 words. A book collection? Millions of words. You simply can't fit everything in the context window.

Methods to Add Custom Knowledge to LLMs

There are several approaches to make LLMs work with your custom data. Let's explore each one in detail:

Method 1: Prompt Engineering (In-Context Learning)

How it works: Paste your data directly into the prompt.

prompt = f"""
You are a story writer. Here are some example passages to follow:

Example 1:
{example_passage_1}

Example 2:
{example_passage_2}

Example 3:
{example_passage_3}

Now write a story about: {user_request}
"""

Pros:

Zero setup - Just copy-paste, no infrastructure needed
Immediate - Results in seconds, no preprocessing
Flexible - Change examples anytime
No training - Works with any off-the-shelf model

Cons:

Context limits - Can only fit 3-10 examples (can't represent diverse styles)
High cost - Pay for example tokens every call ($0.01-0.10 per request)
No intelligence - Must manually choose examples (may pick irrelevant ones)
Doesn't scale - 100 books = impossible

Best for: Quick prototypes, very small datasets (<10 pages)

Method 2: Fine-Tuning

How it works: Train the model's weights on your specific data.

# Conceptual fine-tuning workflow
training_data = [
    {
        "messages": [
            {"role": "system", "content": "You write in xianxia style"},
            {"role": "user", "content": "Write about a breakthrough"},
            {"role": "assistant", "content": "The qi vortex above Chen Wei's head..."}
        ]
    },
    # ... hundreds or thousands more examples
]

# Train the model (this costs money and time!)
fine_tuned_model = openai.fine_tuning.jobs.create(
    training_file="training_data.jsonl",
    model="gpt-3.5-turbo"
)

Pros:

Persistent knowledge - Style/knowledge "baked into" weights
Fast inference - No retrieval step needed
Deep learning - Can learn subtle patterns over time
Consistent outputs - Same style every time

Cons:

Expensive - GPT-3.5 fine-tuning costs $50-500+ per training run
Time-consuming - Hours to days of training, slow iteration
Expertise required - Need to understand ML concepts (high barrier)
Catastrophic forgetting - Model may lose general capabilities
Static knowledge - Can't update without retraining (adding one book = full retrain)
Data preparation - Need to format data properly (hours of prep work)
Overfitting risk - Model memorizes instead of learning

Best for: Production systems with stable data, when you need consistent style

Method 3: RAG (Retrieval-Augmented Generation)

How it works: Store data in a searchable database, retrieve relevant pieces at query time.

# RAG workflow
def generate_with_rag(user_query):
    # 1. Search for relevant content
    relevant_passages = vector_db.search(user_query, top_k=5)

    # 2. Build augmented prompt
    prompt = f"""
    Reference material:
    {relevant_passages}

    User request: {user_query}
    """

    # 3. Generate with context
    return llm.generate(prompt)

Pros:

No training - Use any model off-the-shelf
Easy updates - Add/remove documents instantly
Scalable - Handle millions of documents
Transparent - See exactly what was retrieved
Cost-effective - Only embed once, query forever
Model-agnostic - Same DB works with any LLM
Grounded responses - Output based on real sources

Cons:

Retrieval quality - Bad retrieval = bad output (need good embeddings)
Additional latency - Search adds 100-500ms (slower than fine-tuning)
Infrastructure - Need vector database (more moving parts)
Chunking challenges - How to split documents affects retrieval quality
Context assembly - Retrieved chunks may not flow naturally
Embedding costs - Need to embed all documents (one-time cost)

Best for: Large/dynamic knowledge bases, when data changes frequently

Method 4: Knowledge Graphs

How it works: Structure data as entities and relationships.

[Brandon Sanderson] --wrote--> [Mistborn] --has_magic_system--> [Allomancy]
                                    |
                                    +--has_character--> [Vin]
                                                          |
                                                          +--has_trait--> [Street Urchin]
                                                          +--has_power--> [Mistborn]

Pros:

Explicit relationships - Captures "how things connect"
Complex queries - "Find all characters who use fire magic"
Reasoning - Can infer new relationships
Structured output - Clean, organized data

Cons:

Complex to build - Must define schema, extract entities (weeks of work)
Maintenance burden - New data needs manual structuring (ongoing effort)
Doesn't capture prose - Style/voice can't be graphed (bad for creative writing)
Domain expertise - Need to understand your data deeply (high barrier)

Best for: Structured data, when relationships matter more than content

Method 5: Hybrid Approaches

Combine methods for best results:

Hybrid Approach	How It Works	Best For
RAG + Fine-tuning	Fine-tune for style, RAG for facts	News/research writing
RAG + Knowledge Graph	Graph for structure, RAG for content	Complex domains
Multi-stage RAG	Retrieve, Rerank, Generate	High-precision needs
RAG + Prompt Engineering	RAG retrieves, few-shot guides format	Specific output formats

Comparison Table: All Methods

Criteria	Prompt Eng.	Fine-Tuning	RAG	Knowledge Graph
Setup Time	Minutes	Days	Hours	Weeks
Setup Cost	$0	$50-500	$0-50	$100+
Per-Query Cost	High	Low	Medium	Low
Technical Skill	Low	High	Medium	High
Knowledge Update	Instant	Re-train	Instant	Manual
Max Data Size	~50 pages	Unlimited	Millions of docs	Millions of nodes
Retrieval Intelligence	None	N/A	Semantic	Graph traversal
Output Consistency	Variable	High	Variable	High
Debugging	Easy	Hard	Medium	Medium
Style Learning	Limited	Excellent	Good	Poor
Fact Accuracy	Low	Medium	High	High

Deep Dive: RAG Pros and Cons

Since we're using RAG, let's examine its strengths and weaknesses in detail:

RAG Advantages (Detailed)

1. No Training Required

Fine-tuning workflow:
1. Prepare training data (hours)
2. Format into JSONL (hours)
3. Upload and validate (minutes)
4. Train model (hours-days)
5. Test and iterate (days)
Total: Days to weeks

RAG workflow:
1. Parse documents (minutes)
2. Chunk and embed (minutes-hours)
3. Store in vector DB (minutes)
Total: Hours

2. Easy Knowledge Updates

# Adding a new book to RAG
def add_book(filepath):
    text = parse_ebook(filepath)      # 10 seconds
    chunks = chunk_text(text)          # 1 second
    embeddings = embed(chunks)         # 30 seconds
    vector_db.add(chunks, embeddings)  # 5 seconds
    # Done! New book is searchable

# Adding a new book with fine-tuning
def add_book_finetune(filepath):
    # 1. Prepare new training examples (1 hour)
    # 2. Combine with existing training data (10 min)
    # 3. Re-run fine-tuning job ($50-200, 2-8 hours)
    # 4. Test new model (1 hour)
    # 5. Deploy new model (30 min)
    # Total: ~12 hours and $50-200

3. Scalability

Data Size	Prompt Engineering	Fine-Tuning	RAG
10 pages	Works	Works	Works
100 pages	Too big	Works	Works
1,000 pages	Impossible	Expensive	Works
10,000 pages	Impossible	Very expensive	Works
1M pages	Impossible	Impractical	Works

4. Transparency and Debugging

# With RAG, you can see exactly what the model sees
result = generator.generate("Write about a warrior")

# Debug: What did we retrieve?
print("Retrieved passages:")
for i, passage in enumerate(result.retrieved_context):
    print(f"{i+1}. {passage[:100]}...")
    print(f"   Similarity: {result.scores[i]}")
    print(f"   Source: {result.sources[i]}")

# If output is wrong, you know exactly where to look:
# - Bad retrieval? Improve embeddings or chunking
# - Good retrieval, bad output? Improve prompt

5. Model Agnostic

# Same knowledge base works with ANY model
knowledge_base = VectorDB("./chroma_db")

# Use with Ollama (free, local)
ollama_response = generate(knowledge_base, model="ollama/qwen2.5")

# Use with OpenAI (paid, cloud)
openai_response = generate(knowledge_base, model="gpt-4")

# Use with Claude (paid, cloud)
claude_response = generate(knowledge_base, model="claude-3-sonnet")

# Switch models without rebuilding anything!

6. Cost Effective

Operation	Fine-Tuning Cost	RAG Cost
Initial setup	$50-500	$0-10
Add 1 book	$50-200 (retrain)	~$0.01 (embed)
Add 100 books	$50-200 (retrain)	~$1 (embed)
Query (GPT-4)	~$0.03/query	~$0.04/query
Query (Ollama)	$0	$0

RAG Disadvantages (Detailed)

1. Retrieval Quality Dependency

The RAG Equation:
Final Output Quality = Retrieval Quality × Generation Quality

If retrieval finds irrelevant passages:
- User asks about "sword fighting"
- System retrieves passages about "cooking swords" (wrong!)
- LLM generates cooking-related nonsense

Retrieval failure modes:
- Semantic gap: query and relevant docs use different words
- Chunking errors: relevant info split across chunks
- Embedding limitations: model doesn't understand domain

2. Additional Latency

Request Timeline Comparison:

Direct LLM (no RAG):
[User Query] → [LLM Generate: 500ms] → [Response]
Total: ~500ms

RAG:
[User Query] → [Embed Query: 50ms] → [Vector Search: 100ms] →
[Fetch Documents: 50ms] → [Build Prompt: 10ms] → [LLM Generate: 600ms] → [Response]
Total: ~810ms (+62% slower)

3. Chunking Challenges

The Chunking Dilemma:

Too Small (100 chars):
"The warrior drew his" | "sword and faced the" | "dragon with courage"
→ Loses context, meaningless fragments

Too Large (5000 chars):
[Entire chapter about many topics]
→ Dilutes relevance, wastes context, may retrieve wrong parts

Just Right (500-1000 chars):
[Complete paragraph about sword fighting]
→ Self-contained, meaningful, searchable

But even "just right" has problems:
- Important info may span two chunks
- Context from previous paragraphs lost
- Character names may not appear in every chunk

4. Context Assembly Issues

# Retrieved chunks may not flow naturally
retrieved = [
    "...he defeated the demon lord. THE END.",  # End of chapter 5
    "Chapter 1: The young warrior woke...",      # Beginning of book
    "...said Master Liu. 'Your training...'"     # Middle of dialogue
]

# Assembled context is disjointed!
# The LLM must make sense of this jumble

5. Cold Start Problem

New RAG System:
- No documents indexed yet
- User queries return nothing relevant
- Output quality = base LLM (no improvement)

Solution: Must index documents before system is useful
This takes time for large collections

Current Limitations of RAG

Understanding limitations helps you build better systems:

Retrieval Limitations

Limitation	Description	Workaround
Semantic gap	Different words for same concept	Hybrid search (keyword + semantic)
No cross-document reasoning	Can't connect info across books	Knowledge graphs, multi-hop retrieval
Recency bias	All chunks treated equally	Add timestamp metadata, boost recent
No negation understanding	"not about war" still retrieves war	Better query processing
Fixed chunk boundaries	Important info split across chunks	Overlapping chunks, larger windows

Embedding Limitations

Limitation	Description	Workaround
Domain mismatch	General embeddings miss domain terms	Fine-tune embedding model
Length limits	Most models cap at 512 tokens	Chunk appropriately
Language bias	English-trained models struggle with other languages	Multilingual models
No structured data	Can't embed tables well	Special preprocessing

Generation Limitations

Limitation	Description	Workaround
Context window	Can only fit N retrieved chunks	Summarization, selection
Lost in the middle	LLMs ignore middle of long contexts	Reorder important info to start/end
Hallucination	May still make things up	Fact-checking, citations
Style inconsistency	May not maintain style throughout	More style examples, fine-tuning

Our Tutorial's Specific Limitations

Since this is a learning-focused tutorial, we've made simplifying choices:

┌─────────────────────────────────────────────────────────────────┐
│                 WHAT THIS TUTORIAL COVERS                       │
├─────────────────────────────────────────────────────────────────┤
│  ✓ Basic RAG pipeline (ingest → embed → store → retrieve)       │
│  ✓ Simple fixed-size chunking with overlap                      │
│  ✓ Single embedding model (no fine-tuning)                      │
│  ✓ Basic similarity search (no reranking)                       │
│  ✓ Single-query retrieval (no query expansion)                  │
│  ✓ Straightforward prompt templates                             │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│              PRODUCTION SYSTEMS WOULD ADD                       │
├─────────────────────────────────────────────────────────────────┤
│  ○ Hybrid search (BM25 keyword + semantic vectors)              │
│  ○ Query expansion ("sword" → "sword, blade, weapon")           │
│  ○ Cross-encoder reranking for better precision                 │
│  ○ Semantic chunking (split on topic boundaries)                │
│  ○ Metadata filtering (by author, genre, date)                  │
│  ○ Caching layer for repeated queries                           │
│  ○ Evaluation metrics (retrieval recall, generation quality)    │
│  ○ A/B testing for prompt variations                            │
│  ○ Streaming responses for better UX                            │
│  ○ Rate limiting and cost management                            │
│  ○ Observability (logging, tracing, metrics)                    │
└─────────────────────────────────────────────────────────────────┘

Why We Choose RAG for This Project

Given all the above, here's why RAG is the right choice for our story generator:

1. Our Use Case Fits RAG Perfectly

Requirement	Why RAG Works
Learn from book collection	Easy to add books to vector DB
Multiple genres/styles	Retrieval finds relevant style samples
Users add their own books	No retraining needed
Works offline	Ollama + local ChromaDB
Educational project	RAG is easier to understand and debug

2. The Alternatives Don't Fit

Method	Why Not for This Project
Prompt Engineering	Can't fit entire book collection
Fine-Tuning	Too expensive, can't easily add books
Knowledge Graphs	Style/prose can't be structured as graphs

3. RAG Handles Our Scale

Typical user's book collection:
- 50-200 ebooks
- 5-20 million words total
- 50,000-200,000 chunks

RAG handles this easily:
- ChromaDB can store millions of vectors
- Search takes <100ms even with 200K chunks
- Adding new books takes seconds

4. Style Learning Works Well with RAG

For creative writing, we don't need exact fact retrieval. We need style examples:

# Query: "Write about a warrior discovering a cave"

# RAG retrieves passages about:
# - Warriors in various situations
# - Cave discoveries
# - Mysterious findings

# These serve as STYLE EXAMPLES, not facts
# The LLM learns "how to write" from them
# Output naturally varies based on what's retrieved

RAG Deep Dive: How It Actually Works

Now let's understand the mechanics:

The RAG Pipeline

┌─────────────────────────────────────────────────────────────────┐
│                        RAG PIPELINE                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ╔═══════════════════════════════════════════════════════════╗  │
│  ║  OFFLINE PHASE (One-time setup)                           ║  │
│  ╠═══════════════════════════════════════════════════════════╣  │
│  ║                                                           ║  │
│  ║  Documents ──▶ Parse ──▶ Chunk ──▶ Embed ──▶ Store        ║  │
│  ║                                                           ║  │
│  ║  ┌─────────┐  ┌───────┐  ┌───────┐  ┌───────┐  ┌───────┐ ║   │
│  ║  │ Ebooks  │─▶│Extract│─▶│ Split │─▶│Vector │─▶│ChromaDB ║   │
│  ║  │PDF/EPUB │  │ Text  │  │ 500ch │  │ 384d  │  │        │ ║  │
│  ║  └─────────┘  └───────┘  └───────┘  └───────┘  └───────┘ ║   │
│  ║                                                           ║  │
│  ╚═══════════════════════════════════════════════════════════╝  │
│                                                                 │
│  ╔═══════════════════════════════════════════════════════════╗  │
│  ║  ONLINE PHASE (Every query)                               ║  │
│  ╠═══════════════════════════════════════════════════════════╣  │
│  ║                                                           ║  │
│  ║  Query ──▶ Embed ──▶ Search ──▶ Retrieve ──▶ Augment ──▶ Gen
│  ║                                                           ║  │
│  ║  ┌───────┐  ┌───────┐  ┌───────┐  ┌───────┐  ┌─────────┐ ║   │
│  ║  │"Write │─▶│Query  │─▶│Cosine │─▶│Top 5  │─▶│Prompt + │ ║   │
│  ║  │about..│  │Vector │  │Search │  │Chunks │  │Context  │ ║   │
│  ║  └───────┘  └───────┘  └───────┘  └───────┘  └────┬────┘ ║   │
│  ║                                                    │      ║  │
│  ║                                                    ▼      ║  │
│  ║                                              ┌─────────┐  ║  │
│  ║                                              │   LLM   │  ║  │
│  ║                                              │Generate │  ║  │
│  ║                                              └────┬────┘  ║  │
│  ║                                                   │       ║  │
│  ║                                                   ▼       ║  │
│  ║                                              ┌─────────┐  ║  │
│  ║                                              │  Story  │  ║  │
│  ║                                              │ Output  │  ║  │
│  ║                                              └─────────┘  ║  │
│  ╚═══════════════════════════════════════════════════════════╝  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Step 1: Document Parsing

# We support multiple ebook formats
def parse_ebook(filepath):
    ext = filepath.suffix.lower()

    if ext == '.pdf':
        return extract_pdf_text(filepath)    # PyMuPDF
    elif ext == '.epub':
        return extract_epub_text(filepath)   # ebooklib
    elif ext == '.mobi':
        return extract_mobi_text(filepath)   # mobi library
    elif ext == '.txt':
        return filepath.read_text()

# Output: Raw text string
# "Chapter 1\n\nThe young warrior stood at the edge..."

Step 2: Text Chunking

Why we chunk:

Problem: A novel has 80,000 words
- Can't embed entire book (embedding models have limits)
- Can't retrieve entire book (wastes context window)
- Need granularity for relevant retrieval

Solution: Split into chunks
- Each chunk is self-contained
- Small enough to embed
- Large enough to be meaningful

Chunking strategies compared:

Strategy	Example	Pros	Cons
Fixed-size	Every 500 characters	Simple, consistent	May cut mid-sentence
Sentence	Split on periods	Natural boundaries	Variable sizes
Paragraph	Split on newlines	Preserves context	Very variable sizes
Semantic	Split on topic change	Best relevance	Complex, slow

We use fixed-size with overlap:

def chunk_text(text, size=500, overlap=50):
    chunks = []
    start = 0

    while start < len(text):
        end = start + size
        chunk = text[start:end]

        # Try to break at sentence boundary
        last_period = chunk.rfind('. ')
        if last_period > size * 0.5:
            chunk = chunk[:last_period + 1]
            end = start + last_period + 1

        chunks.append(chunk)
        start = end - overlap  # Overlap!

    return chunks

Text: [AAAAA][BBBBB][CCCCC][DDDDD][EEEEE]

Chunks with overlap:
1: [AAAAA][BB]
2:    [BB][BBBBB][CC]
3:          [CC][CCCCC][DD]
4:                [DD][DDDDD][EE]
5:                      [EE][EEEEE]

Overlap ensures we don't lose context at boundaries!

Step 3: Embedding

Convert text to vectors that capture meaning:

from sentence_transformers import SentenceTransformer

# Load model (downloads ~100MB first time)
model = SentenceTransformer('paraphrase-multilingual-MiniLM-L12-v2')

# Embed text
text = "The warrior drew his ancient blade"
vector = model.encode(text)

print(vector.shape)  # (384,)
print(vector[:5])    # [0.23, -0.45, 0.67, 0.12, -0.89]

Why embeddings work:

# Similar meanings → Similar vectors
v1 = embed("The warrior drew his sword")
v2 = embed("The fighter unsheathed his blade")
v3 = embed("I like pizza")

cosine_similarity(v1, v2)  # 0.89 - very similar!
cosine_similarity(v1, v3)  # 0.12 - very different!

Step 4: Vector Storage (ChromaDB)

import chromadb

# Create persistent database
client = chromadb.PersistentClient(path="./chroma_db")

# Create collection
collection = client.create_collection(
    name="story_styles",
    metadata={"description": "Writing style samples"}
)

# Add documents
collection.add(
    ids=["chunk_001", "chunk_002", "chunk_003"],
    documents=[
        "The warrior drew his blade...",
        "Magic sparkled in the air...",
        "The ancient tome revealed..."
    ],
    embeddings=[
        [0.23, -0.45, ...],  # 384 dimensions
        [0.12, 0.67, ...],
        [-0.34, 0.21, ...]
    ],
    metadatas=[
        {"source": "book1.txt", "chunk_id": 1},
        {"source": "book1.txt", "chunk_id": 2},
        {"source": "book2.txt", "chunk_id": 1}
    ]
)

print(f"Stored {collection.count()} chunks")

Step 5: Retrieval

# User's query
query = "A young cultivator discovers a mysterious cave"

# Embed the query
query_vector = model.encode(query)

# Search for similar chunks
results = collection.query(
    query_embeddings=[query_vector],
    n_results=5,
    include=["documents", "distances", "metadatas"]
)

# Results contain the most relevant passages
for i, doc in enumerate(results['documents'][0]):
    print(f"Result {i+1} (distance: {results['distances'][0][i]:.3f}):")
    print(f"  {doc[:100]}...")
    print(f"  Source: {results['metadatas'][0][i]['source']}")

Step 6: Augmented Generation

# Build the augmented prompt
def build_prompt(query, retrieved_passages):
    context = "\n\n---\n\n".join(retrieved_passages)

    prompt = f"""Here are some example passages showing the writing style to follow:

{context}

---

Now write a NEW story passage in a similar style.
Story idea: {query}

Requirements:
- Match the writing style of the examples above
- Create original content (don't copy)
- Include vivid descriptions and dialogue

Story:
"""
    return prompt

# Generate
prompt = build_prompt(user_query, retrieved_passages)
story = llm.generate(prompt)

The Architecture for Our Story Generator

┌────────────────────────────────────────────────────────────────────────┐
│                     AI RAG STORY GENERATOR                              │
├────────────────────────────────────────────────────────────────────────┤
│                                                                        │
│   YOUR EBOOK COLLECTION                                                │
│   ┌──────────────────────────────────────────────────────────────┐    │
│   │  data/raw/                                                    │    │
│   │  ├── fantasy_novel.epub                                       │    │
│   │  ├── xianxia_story.pdf                                        │    │
│   │  ├── magic_school.mobi                                        │    │
│   │  └── cultivation_tale.txt                                     │    │
│   └──────────────────────────────────────────────────────────────┘    │
│                              │                                         │
│                              ▼                                         │
│   ┌──────────────────────────────────────────────────────────────┐    │
│   │  PARSE (parse_ebooks.py)                                      │    │
│   │  • Extract text from PDF, EPUB, MOBI, TXT                     │    │
│   │  • Clean and normalize text                                   │    │
│   │  • Output: data/txt/*.txt                                     │    │
│   └──────────────────────────────────────────────────────────────┘    │
│                              │                                         │
│                              ▼                                         │
│   ┌──────────────────────────────────────────────────────────────┐    │
│   │  BUILD DATABASE (build_style_db.py)                           │    │
│   │  • Chunk text (500 chars, 50 overlap)                         │    │
│   │  • Generate embeddings (SentenceTransformer)                  │    │
│   │  • Store in ChromaDB                                          │    │
│   │  • Output: chroma_db/                                         │    │
│   └──────────────────────────────────────────────────────────────┘    │
│                              │                                         │
│                              ▼                                         │
│   ┌──────────────────────────────────────────────────────────────┐    │
│   │  VECTOR DATABASE (ChromaDB)                                   │    │
│   │  • Stores: text chunks + embeddings + metadata                │    │
│   │  • Enables: fast similarity search                            │    │
│   │  • Persists: survives restarts                                │    │
│   └──────────────────────────────────────────────────────────────┘    │
│                              │                                         │
│         ┌────────────────────┴────────────────────┐                   │
│         │                                         │                    │
│         ▼                                         ▼                    │
│   ┌─────────────┐                          ┌─────────────┐            │
│   │  CLI MODE   │                          │   WEB UI    │            │
│   │ generate_   │                          │   app.py    │            │
│   │ with_style  │                          │  (Gradio)   │            │
│   │    .py      │                          │             │            │
│   └──────┬──────┘                          └──────┬──────┘            │
│          │                                        │                    │
│          └────────────────┬───────────────────────┘                   │
│                           │                                            │
│                           ▼                                            │
│   ┌──────────────────────────────────────────────────────────────┐    │
│   │  GENERATION PIPELINE                                          │    │
│   │                                                               │    │
│   │  User: "Write about a cultivator finding a cave"             │    │
│   │                           │                                   │    │
│   │                           ▼                                   │    │
│   │  ┌─────────────────────────────────────────────────────────┐ │    │
│   │  │ 1. Embed query with SentenceTransformer                 │ │    │
│   │  └─────────────────────────────────────────────────────────┘ │    │
│   │                           │                                   │    │
│   │                           ▼                                   │    │
│   │  ┌─────────────────────────────────────────────────────────┐ │    │
│   │  │ 2. Search ChromaDB for similar passages                 │ │    │
│   │  │    Returns: 3-5 style samples                           │ │    │
│   │  └─────────────────────────────────────────────────────────┘ │    │
│   │                           │                                   │    │
│   │                           ▼                                   │    │
│   │  ┌─────────────────────────────────────────────────────────┐ │    │
│   │  │ 3. Build augmented prompt                               │ │    │
│   │  │    [Style examples] + [User request]                    │ │    │
│   │  └─────────────────────────────────────────────────────────┘ │    │
│   │                           │                                   │    │
│   │                           ▼                                   │    │
│   │  ┌─────────────────────────────────────────────────────────┐ │    │
│   │  │ 4. Send to LLM                                          │ │    │
│   │  │    ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐     │ │    │
│   │  │    │ Ollama  │ │ OpenAI  │ │ Claude  │ │ Gemini  │     │ │    │
│   │  │    │ (local) │ │  (API)  │ │  (API)  │ │  (API)  │     │ │    │
│   │  │    └─────────┘ └─────────┘ └─────────┘ └─────────┘     │ │    │
│   │  └─────────────────────────────────────────────────────────┘ │    │
│   │                           │                                   │    │
│   │                           ▼                                   │    │
│   │  ┌─────────────────────────────────────────────────────────┐ │    │
│   │  │ 5. Return generated story in learned style              │ │    │
│   │  └─────────────────────────────────────────────────────────┘ │    │
│   └──────────────────────────────────────────────────────────────┘    │
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘

What We'll Build in This Series

Part 1 (This Article)

✅ Understanding RAG concepts
✅ Comparing all alternatives in detail
✅ Deep dive into RAG pros and cons
✅ Current limitations
✅ Why we chose RAG
✅ How RAG works step-by-step
✅ Architecture overview

Part 2: Building the RAG Pipeline

Project setup and dependencies
Parsing ebooks (PDF, EPUB, MOBI) with code
Text chunking implementation
Generating embeddings with Sentence Transformers
Storing in ChromaDB
Testing retrieval quality

Part 3: Story Generation

Connecting to LLMs (Ollama, OpenAI, Claude)
Prompt engineering for style transfer
Single chapter generation
Multi-chapter story generation
Maintaining consistency with summaries
Web interface with Gradio

Prerequisites

Before Part 2, make sure you have:

Python 3.10+ installed
8GB+ RAM (16GB recommended for larger models)
Some ebooks to learn from (any genre!)
(Optional) Ollama for local LLM inference

Clone the repository:

git clone https://github.com/namtran/ai-rag-tutorial-story-generator.git
cd ai-rag-tutorial-story-generator

Summary

Topic	Key Takeaway
The Problem	LLMs don't know your custom data, have knowledge cutoffs, and generate generic content
Alternatives	Prompt engineering (simple but limited), Fine-tuning (powerful but expensive), RAG (balanced), Knowledge graphs (structured data)
RAG Pros	No training, easy updates, scalable, transparent, cost-effective, model-agnostic
RAG Cons	Retrieval quality dependency, added latency, chunking challenges, context assembly issues
Limitations	Semantic gaps, embedding limits, no cross-document reasoning (in basic RAG)
Why RAG for Us	Fits our use case perfectly: large book collections, easy updates, style learning
How RAG Works	Parse, Chunk, Embed, Store, Query, Retrieve, Augment, Generate

Next Article: Part 2: Building the RAG Pipeline →

Source Code: github.com/namtran/ai-rag-tutorial-story-generator

Found this helpful? Follow me for Parts 2 and 3!

18 Years in Software Development: From Symbian C++ to Swift, From Employee to Indie Developer

Nam Tran — Mon, 19 Jan 2026 13:16:52 +0000

I still remember the weight of my first Symbian phone, the way C++ felt like wrestling with a beast that occasionally rewarded you with something beautiful. That was 2008, right after I graduated from university. I was young, hungry, and had no idea that eighteen years later, I'd still be here — older, still hungry, and somehow more in love with this craft than ever.

This is my story. Not a success story, not yet. But a story of persistence, late nights, failed projects, and a heartbeat that refuses to slow down.

The Early Days: When Mobile Meant Something Different

My career began with C++ and Symbian OS — a world that feels prehistoric now. Back then, writing mobile apps meant fighting memory constraints, dealing with cryptic documentation, and celebrating when your app didn't crash the entire phone.

Then came J2ME. If you know, you know. The fragmentation nightmare. Testing on dozens of devices with different screen sizes, different capabilities, different bugs. We wrote apps that fit in kilobytes and felt like magicians when they worked.

I moved to Windows application development, then to automotive HMI systems — those sleek interfaces you see in car dashboards. Different industries, different challenges, same passion.

But something was always pulling me back to mobile. To that direct connection between code and the device in someone's hand.

The Stress That Almost Won

I won't romanticize it. Software development is stressful. The deadlines that don't care about your personal life. The bugs that appear at 11 PM before a major release. The constant feeling that technology is moving faster than you can learn.

I tried to quit. Multiple times.

I told myself I'd find something easier, something that wouldn't consume my nights and weekends. Something that wouldn't make me question my sanity when a semicolon cost me three hours of debugging.

But every time I walked away, something pulled me back. A spark. An idea. That entrepreneurial heartbeat that grew stronger with every attempt to silence it.

2013: The $200 Decision That Changed Everything

In 2013, I bought my first MacBook. It was old, used, and cost about $200. But it was mine, and it was a gateway.

I wanted to learn Swift. Not for work. Not for anyone else. For myself.

I wrote code at night after my day job. Weekends disappeared into Xcode. I was building something that didn't exist yet — my future as an indie developer.

Then came the real commitment: a brand new MacBook Pro 2013. Nearly $2,000. For someone betting on themselves, that wasn't just a purchase. It was a declaration.

I am doing this. I am becoming an indie developer.

The First Apps: Small Steps, Big Dreams

Flashcard for Kids was my first real app in 2014. Nothing revolutionary. Just a simple educational tool. But seeing it on the App Store, knowing that somewhere a child might learn something because of code I wrote — that feeling is impossible to describe.

A year later came English For Kids. Then more a dozen apps. Each one taught me something new. Each one failed in different ways. Each one kept me going.

2026: DiskCleanKit and PhoneCleanKit

Fast forward to now. I just released DiskCleanKit on Mac and PhoneCleanKit on iOS. Storage cleaning utilities. Practical tools for real problems.

Are they successful? Not yet.

But here's what I've learned after eighteen years: success isn't a destination. It's the accumulation of all those late nights, all those failed projects, all those moments when you could have quit but didn't.

The Secret Nobody Tells You

You want to know if you're cut out for this? Here's the test:

Can you work until midnight and still feel excited to wake up early tomorrow to keep coding?

Not because you have to. Because you want to. Because there's something unfinished that's calling you. Because your brain is already solving problems while you sleep.

If yes — you're one of us.

On Failed Projects

I've lost count of my failed projects. Apps that nobody downloaded. Features that nobody used. Ideas that seemed brilliant at 2 AM and embarrassing by morning.

I don't care.

Every failed project taught me something. Every "wasted" effort built skills I'd use later. And most importantly — I always have something new to work on tomorrow.

That's the gift of being a developer. There's always another problem to solve, another idea to pursue, another version to ship.

AI Won't Replace Us — We Direct It

I use AI now. It speeds up my work significantly. What took days sometimes takes hours. What took hours sometimes takes minutes.

But I disagree with those who say developers will become obsolete. Elon Musk and others paint a picture of AI writing all the code while we watch.

That's not how it works. That's not how it will work.

We are not just people who type code. We are problem solvers. We are architects. We are the ones who understand what needs to be built and why. AI is a powerful tool — perhaps the most powerful tool we've ever had — but it's still a tool.

We manage it. We control it. We direct it.

The code is just the expression of our ideas. And ideas? Those still come from us.

We are the creators. We are the developers.

The Road Ahead

I don't know if DiskCleanKit will become successful. I don't know if PhoneCleanKit will find its audience. I don't know what the next eighteen years will bring.

But I know this: I'll keep building.

I'll keep learning new technologies when they emerge. I'll keep adapting when the industry shifts. I'll keep working late nights when an idea won't let me sleep.

I made a promise to myself — to continue in software development until I physically cannot. Not because I have to. Because this is who I am.

From Symbian to Swift. From employee to entrepreneur. From that $200 MacBook to wherever this journey takes me next.

The apps might not be successful yet. But the developer? After eighteen years of trying to quit and coming back stronger each time?

That developer has already won.

If you're on your own indie journey, I'd love to hear your story. Drop a comment below. We're all in this together.

My Current Projects:

🖥️ DiskCleanKit — Storage cleaner for Mac
📱 PhoneCleanKit — Storage cleaner for iOS

Follow me for more stories about indie development and the entrepreneurial journey.

Liquid Glass in Swift: Official Best Practices for iOS 26 & macOS Tahoe

Nam Tran — Fri, 16 Jan 2026 06:27:11 +0000

iOS 26 and macOS Tahoe introduce Liquid Glass—Apple's unified design language. This guide compiles official Apple guidelines from WWDC 2025 sessions to help you integrate Liquid Glass correctly.

What is Liquid Glass?

From Apple's WWDC 2025 Session 219:

"Liquid Glass is a new digital meta-material that dynamically bends and shapes light."

Key difference: Liquid Glass uses "Lensing"—bending and concentrating light, not scattering it like traditional blur.

Part 1: What You Get FREE (Zero Code)

Recompile with Xcode 26 and these get Liquid Glass automatically:

iOS 26:

NavigationBar, TabBar, Toolbar
Sheets, Popovers, Menus, Alerts
Search bars, Control Center
Toggles, Sliders, Pickers (during interaction)

macOS Tahoe:

Toolbar, Sidebar, Menu bar, Dock
Window controls, NSPopover, Sheets

// This automatically gets Liquid Glass!
NavigationStack {
    List(items) { item in
        Text(item.name)
    }
    .toolbar {
        ToolbarItem(placement: .topBarTrailing) {
            Button("Add", systemImage: "plus") { }
        }
    }
}

Part 2: The Golden Rule - Navigation Layer Only

From Apple WWDC 2025:

"Liquid Glass is best reserved for the navigation layer that floats above the content of your app."

✅ Use Glass For:

Toolbars, TabBars, Sidebars
Floating action buttons
Sheets, popovers, menus

❌ Never Use Glass For:

Content layer (lists, cards, tables)
Full-screen backgrounds
Scrollable content

// ❌ WRONG - Glass on content
List {
    ForEach(items) { item in
        Text(item.name)
            .glassEffect()  // DON'T!
    }
}

// ✅ CORRECT - Glass only on floating controls
ZStack {
    List { /* content without glass */ }

    VStack {
        Spacer()
        FloatingButton()
            .glassEffect(.regular.interactive())
    }
}

Part 3: Never Stack Glass on Glass

From Apple WWDC 2025:

"Always avoid glass on glass. Stacking Liquid Glass elements can quickly make the interface feel cluttered."

Why? Glass cannot properly sample other glass.

// ❌ WRONG
VStack {
    HeaderView().glassEffect()
    ContentView().glassEffect()  // Glass on glass!
}

// ✅ CORRECT - Single glass layer
ZStack {
    ContentView()  // No glass
    FloatingControls().glassEffect()  // Single layer
}

Part 4: GlassEffectContainer - The Essential API

From Apple WWDC 2025 Session 323:

"Group multiple glass elements within a GlassEffectContainer because glass cannot sample other glass."

Always Use Container for Multiple Elements

// ✅ CORRECT
GlassEffectContainer {
    HStack(spacing: 16) {
        Button("Edit") { }.glassEffect()
        Button("Share") { }.glassEffect()
        Button("Delete") { }.glassEffect()
    }
}

// ❌ WRONG - Without container
HStack {
    Button("Edit") { }.glassEffect()
    Button("Share") { }.glassEffect()
}
// Each samples independently = inconsistent!

Benefits of GlassEffectContainer

Shared sampling region - Consistent appearance
Better performance - Single render pass
Enables morphing - Fluid transitions
Automatic grouping - Elements blend when close

Spacing Parameter

GlassEffectContainer(spacing: 30) {
    // Elements within 30pt morph together
    HStack(spacing: 20) {
        Button("A") { }.glassEffect()
        Button("B") { }.glassEffect()
    }
}

Part 5: Morphing with glassEffectID

Create fluid transitions between glass elements:

struct ExpandableMenu: View {
    @State private var isExpanded = false
    @Namespace private var namespace

    var body: some View {
        GlassEffectContainer(spacing: 20) {
            HStack(spacing: 16) {
                if isExpanded {
                    Button("Camera", systemImage: "camera") { }
                        .glassEffect(.regular.interactive())
                        .glassEffectID("camera", in: namespace)

                    Button("Photos", systemImage: "photo") { }
                        .glassEffect(.regular.interactive())
                        .glassEffectID("photos", in: namespace)
                }

                Button {
                    withAnimation(.bouncy) {
                        isExpanded.toggle()
                    }
                } label: {
                    Image(systemName: isExpanded ? "xmark" : "plus")
                        .frame(width: 44, height: 44)
                }
                .buttonStyle(.glassProminent)
                .buttonBorderShape(.circle)
                .glassEffectID("toggle", in: namespace)
            }
        }
    }
}

Requirements for morphing:

Elements in same GlassEffectContainer
Each has glassEffectID with shared namespace
Animation applied to state changes

Part 6: Regular vs Clear Variants

From Apple WWDC 2025:

"They should never be mixed, as they each have their own characteristics."

Regular (Default) - Use for Most Cases

.glassEffect(.regular)  // or just .glassEffect()

Clear - Only When ALL Three Conditions Met:

Over media-rich content (photos, videos)
Content won't suffer from dimming layer
Content above is bold and bright

// Photo editor controls
ZStack {
    Image("photo")

    HStack {
        Button("Filters") { }
            .glassEffect(.clear.interactive())
    }
}

Never Mix Variants

// ❌ WRONG
HStack {
    Button("A") { }.glassEffect(.regular)
    Button("B") { }.glassEffect(.clear)  // Don't mix!
}

Part 7: Tinting - Primary Actions Only

From Apple WWDC 2025:

"Tinting should only be used to bring emphasis to primary elements and actions."

// ✅ CORRECT - Only primary action tinted
HStack {
    Button("Cancel") { }
        .buttonStyle(.glass)  // No tint

    Button("Save") { }
        .buttonStyle(.glassProminent)
        .tint(.blue)  // Primary action
}

// ❌ WRONG - Everything tinted
HStack {
    Button("A") { }.glassEffect(.regular.tint(.blue))
    Button("B") { }.glassEffect(.regular.tint(.green))
    Button("C") { }.glassEffect(.regular.tint(.red))
}
// When everything is tinted, nothing stands out!

Part 8: Button Styles

Style	Appearance	Use Case
`.glass`	Translucent	Secondary actions
`.glassProminent`	Opaque	Primary actions

HStack {
    Button("Cancel") { }
        .buttonStyle(.glass)

    Button("Confirm") { }
        .buttonStyle(.glassProminent)
        .tint(.green)
}

Part 9: Interactive Modifier (iOS Only)

// iOS - Touch feedback
Button("Tap") { }
    .glassEffect(.regular.interactive())

Behaviors: Scales, bounces, shimmers, illuminates from touch point.

Part 10: macOS Specifics

AppKit Glass Bezel

let button = NSButton()
button.bezelStyle = .glass
button.bezelColor = .systemBlue

Automatic Toolbar Grouping

AppKit groups multiple toolbar buttons on one glass piece. Use NSToolbarItemGroup or spacers to override.

Sidebar Ambient Reflection

On macOS/iPad, sidebars reflect light from nearby colorful content automatically.

Part 11: Accessibility - Automatic

From Apple WWDC 2025:

"These are available automatically whenever you use the new material."

Setting	Effect
Reduce Transparency	Frostier glass
Increase Contrast	Black/white with border
Reduce Motion	Disabled elastic effects

No extra code needed!

Quick Reference: Do's and Don'ts

✅ DO

// Container for multiple elements
GlassEffectContainer {
    HStack {
        Button("A") { }.glassEffect()
        Button("B") { }.glassEffect()
    }
}

// Morphing IDs
.glassEffectID("btn", in: namespace)

// Interactive on iOS
.glassEffect(.regular.interactive())

// Tint only primary actions
.buttonStyle(.glassProminent).tint(.blue)

❌ DON'T

// Glass on content
List { ... }.glassEffect()

// Glass on glass
VStack {
    View1().glassEffect()
    View2().glassEffect()
}

// Mix variants
.glassEffect(.regular)
.glassEffect(.clear)

// Tint everything
.glassEffect(.regular.tint(.blue))

// Multiple glass without container
HStack {
    Button("A") { }.glassEffect()
    Button("B") { }.glassEffect()
}

API Quick Reference

// Basic
.glassEffect()
.glassEffect(.regular)
.glassEffect(.clear)

// With shape
.glassEffect(.regular, in: .capsule)
.glassEffect(.regular, in: .circle)

// Modifiers
.glassEffect(.regular.tint(.blue))
.glassEffect(.regular.interactive())

// Container
GlassEffectContainer(spacing: 30) { }

// Morphing
.glassEffectID("id", in: namespace)

// Button styles
.buttonStyle(.glass)
.buttonStyle(.glassProminent)

Conclusion

Remember the core principles:

Navigation layer only - Never content
Never stack glass on glass
Use GlassEffectContainer for multiple elements
Tint selectively - Primary actions only
Trust the system - Accessibility is automatic

Official Resources:

Apple's Official Documentation

Building Bridgeless TurboModules in React Native 0.74+: A Practical Guide

Nam Tran — Fri, 09 Jan 2026 01:57:23 +0000

React Native 0.74 marked a major milestone: the TurboModule interop proxy was removed. Before 0.74, TurboModules still passed through an interop layer that added overhead. Now, with true bridgeless mode, JavaScript communicates directly with native code via JSI bindings - no proxy, no serialization, no bridge.

In this guide, I'll show you how to build a simple AuthModule with a synchronous isUserLoggedIn() method - a practical example that demonstrates the real performance benefits.

What Changed in React Native 0.74+

Before 0.74: TurboModule with Interop Proxy

JS → TurboModule Proxy → Interop Layer → Native Module
         ↓
    (still had serialization overhead)

Even with TurboModules enabled, the interop layer maintained backward compatibility with old bridge modules, adding latency.

0.74+ True Bridgeless

JS → JSI Binding → Native Code
        ↓
   (direct memory access, zero-copy)

The proxy is gone. Your TurboModule methods are now direct C++ function calls exposed to JavaScript.

Performance Comparison

React Native Version	`isUserLoggedIn()` call
Old Bridge	~5-10ms
0.73 TurboModule (with proxy)	~0.5-1ms
0.74+ Bridgeless (no proxy)	~0.05ms

What We're Building

A simple authentication module:

import AuthModule from './specs/NativeAuthModule';

// Sync method - instant return, no await
const isLoggedIn = AuthModule.isUserLoggedIn(); // true or false

// Async methods
const user = await AuthModule.getCurrentUser();
await AuthModule.login('user@example.com', 'password123');
await AuthModule.logout();

Project Setup

Prerequisites

React Native 0.74+ (0.76+ recommended for stable bridgeless)
Xcode 15+

1. Enable New Architecture

ios/Podfile:

ENV['RCT_NEW_ARCH_ENABLED'] = '1'

2. Enable Bridgeless Mode

For React Native 0.74-0.75, add to ios/YourApp/AppDelegate.mm:

// In your AppDelegate
- (BOOL)bridgelessEnabled {
  return YES;
}

For React Native 0.76+, bridgeless is the default. You can explicitly enable it in react-native.config.js:

module.exports = {
  project: {
    ios: {
      unstable_reactLegacyComponentNames: [], // empty = bridgeless
    },
  },
};

3. Install Pods

cd ios && RCT_NEW_ARCH_ENABLED=1 pod install

Step 1: Create the TypeScript Spec

Codegen uses this spec to generate native bindings.

src/specs/NativeAuthModule.ts:

import type { TurboModule } from 'react-native';
import { TurboModuleRegistry } from 'react-native';

export interface Spec extends TurboModule {
  // Sync method - executes immediately, blocks JS briefly
  isUserLoggedIn(): boolean;

  // Async methods - return Promises
  getCurrentUser(): Promise<{
    id: string;
    email: string;
    name: string;
  } | null>;

  login(email: string, password: string): Promise<boolean>;

  logout(): Promise<void>;
}

// getEnforcing throws if module not found (good for debugging)
export default TurboModuleRegistry.getEnforcing<Spec>('AuthModule');

package.json - Add Codegen config:

{
  "codegenConfig": {
    "name": "AuthModuleSpec",
    "type": "modules",
    "jsSrcsDir": "src/specs"
  }
}

Step 2: Objective-C Implementation

Header File

ios/AuthModule.h:

#import <React/RCTBridgeModule.h>
#import <ReactCommon/RCTTurboModule.h>

@interface AuthModule : NSObject <RCTBridgeModule, RCTTurboModule>
@end

Implementation File

ios/AuthModule.mm:

#import "AuthModule.h"
#import <React/RCTBridge+Private.h>

// Codegen generates this header after `pod install`
#ifdef RCT_NEW_ARCH_ENABLED
#import <AuthModuleSpec/AuthModuleSpec.h>
#endif

@implementation AuthModule

RCT_EXPORT_MODULE(AuthModule)

#pragma mark - Configuration

// IMPORTANT: Return NO to enable synchronous methods
+ (BOOL)requiresMainQueueSetup {
  return NO;
}

// Connect to TurboModule system - this is what makes bridgeless work
- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
    (const facebook::react::ObjCTurboModule::InitParams &)params {
#ifdef RCT_NEW_ARCH_ENABLED
  return std::make_shared<facebook::react::NativeAuthModuleSpecJSI>(params);
#else
  return nullptr;
#endif
}

#pragma mark - Synchronous Method (True Bridgeless - No Proxy!)

// RCT_EXPORT_SYNCHRONOUS_TYPED_METHOD enables sync calls
// In 0.74+ bridgeless, this is a direct JSI call - no interop proxy
RCT_EXPORT_SYNCHRONOUS_TYPED_METHOD(NSNumber *, isUserLoggedIn) {
  // This runs synchronously on the JS thread
  // Keep it fast! (< 1ms ideally)
  NSString *token = [[NSUserDefaults standardUserDefaults] 
                     stringForKey:@"userToken"];
  BOOL isLoggedIn = (token != nil && token.length > 0);
  return @(isLoggedIn);
}

#pragma mark - Async Methods

RCT_EXPORT_METHOD(getCurrentUser:(RCTPromiseResolveBlock)resolve
                          reject:(RCTPromiseRejectBlock)reject) {
  // Move to background thread for any I/O
  dispatch_async(dispatch_get_global_queue(QOS_CLASS_USER_INITIATED, 0), ^{
    NSString *token = [[NSUserDefaults standardUserDefaults] 
                       stringForKey:@"userToken"];

    if (!token || token.length == 0) {
      resolve([NSNull null]);
      return;
    }

    // In production: decode JWT or fetch from API
    NSDictionary *user = @{
      @"id": @"user_123",
      @"email": @"user@example.com",
      @"name": @"John Doe"
    };

    resolve(user);
  });
}

RCT_EXPORT_METHOD(login:(NSString *)email
                password:(NSString *)password
                 resolve:(RCTPromiseResolveBlock)resolve
                  reject:(RCTPromiseRejectBlock)reject) {
  dispatch_async(dispatch_get_global_queue(QOS_CLASS_USER_INITIATED, 0), ^{
    // In production: call your authentication API
    if (email.length > 0 && password.length >= 6) {
      [[NSUserDefaults standardUserDefaults] setObject:@"mock_token_123" 
                                                forKey:@"userToken"];
      resolve(@YES);
    } else {
      reject(@"AUTH_ERROR", @"Invalid email or password", nil);
    }
  });
}

RCT_EXPORT_METHOD(logout:(RCTPromiseResolveBlock)resolve
                  reject:(RCTPromiseRejectBlock)reject) {
  [[NSUserDefaults standardUserDefaults] removeObjectForKey:@"userToken"];
  resolve([NSNull null]);
}

@end

Why This Is Faster in 0.74+ Bridgeless

// When JS calls: AuthModule.isUserLoggedIn()

// OLD (with bridge):
// 1. JS serializes call to JSON
// 2. Message queued in bridge
// 3. Native deserializes JSON
// 4. Method executes
// 5. Result serialized to JSON
// 6. Response queued
// 7. JS deserializes response

// 0.74+ BRIDGELESS (no proxy):
// 1. JSI calls C++ binding directly
// 2. Method executes
// 3. Result returned via JSI
// That's it. Direct function call.

Step 3: Swift Implementation

Swift modules need an Objective-C bridging layer for TurboModule compatibility.

Swift Module

ios/AuthModuleSwift.swift:

import Foundation

@objc(AuthModuleSwift)
class AuthModuleSwift: NSObject {

  // MARK: - Configuration

  @objc static func requiresMainQueueSetup() -> Bool {
    return false  // Required for sync methods
  }

  @objc static func moduleName() -> String {
    return "AuthModuleSwift"
  }

  // MARK: - Synchronous Method

  // This is called directly via JSI in bridgeless mode
  @objc func isUserLoggedInSync() -> NSNumber {
    let token = UserDefaults.standard.string(forKey: "userToken")
    let isLoggedIn = token != nil && !token!.isEmpty
    return NSNumber(value: isLoggedIn)
  }

  // MARK: - Async Methods

  @objc func getCurrentUser(
    _ resolve: @escaping RCTPromiseResolveBlock,
    reject: @escaping RCTPromiseRejectBlock
  ) {
    DispatchQueue.global(qos: .userInitiated).async {
      guard let token = UserDefaults.standard.string(forKey: "userToken"),
            !token.isEmpty else {
        resolve(NSNull())
        return
      }

      let user: [String: Any] = [
        "id": "user_123",
        "email": "user@example.com",
        "name": "John Doe"
      ]
      resolve(user)
    }
  }

  @objc func login(
    _ email: String,
    password: String,
    resolve: @escaping RCTPromiseResolveBlock,
    reject: @escaping RCTPromiseRejectBlock
  ) {
    DispatchQueue.global(qos: .userInitiated).async {
      if !email.isEmpty && password.count >= 6 {
        UserDefaults.standard.set("mock_token_123", forKey: "userToken")
        resolve(true)
      } else {
        reject("AUTH_ERROR", "Invalid email or password", nil)
      }
    }
  }

  @objc func logout(
    _ resolve: @escaping RCTPromiseResolveBlock,
    reject: @escaping RCTPromiseRejectBlock
  ) {
    UserDefaults.standard.removeObject(forKey: "userToken")
    resolve(NSNull())
  }
}

Objective-C Bridge for Swift

ios/AuthModuleSwift.m:

#import <React/RCTBridgeModule.h>

@interface RCT_EXTERN_MODULE(AuthModuleSwift, NSObject)

// Sync method - note the special macro
RCT_EXTERN__BLOCKING_SYNCHRONOUS_METHOD(isUserLoggedInSync)

// Async methods
RCT_EXTERN_METHOD(getCurrentUser:
                  (RCTPromiseResolveBlock)resolve
                  reject:(RCTPromiseRejectBlock)reject)

RCT_EXTERN_METHOD(login:
                  (NSString *)email
                  password:(NSString *)password
                  resolve:(RCTPromiseResolveBlock)resolve
                  reject:(RCTPromiseRejectBlock)reject)

RCT_EXTERN_METHOD(logout:
                  (RCTPromiseResolveBlock)resolve
                  reject:(RCTPromiseRejectBlock)reject)

@end

TurboModule Wrapper for Swift (Full Bridgeless)

ios/AuthModuleSwiftTurbo.mm:

#ifdef RCT_NEW_ARCH_ENABLED
#import <React/RCTBridgeModule.h>
#import <ReactCommon/RCTTurboModule.h>
#import <AuthModuleSpec/AuthModuleSpec.h>
#import "YourApp-Swift.h"  // Xcode generates this

@interface AuthModuleSwiftTurbo : NSObject <NativeAuthModuleSpec>
@property (nonatomic, strong) AuthModuleSwift *swiftImpl;
@end

@implementation AuthModuleSwiftTurbo

RCT_EXPORT_MODULE(AuthModuleSwift)

- (instancetype)init {
  if (self = [super init]) {
    _swiftImpl = [[AuthModuleSwift alloc] init];
  }
  return self;
}

+ (BOOL)requiresMainQueueSetup {
  return NO;
}

- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
    (const facebook::react::ObjCTurboModule::InitParams &)params {
  return std::make_shared<facebook::react::NativeAuthModuleSpecJSI>(params);
}

// Delegate all methods to Swift implementation
- (NSNumber *)isUserLoggedIn {
  return [_swiftImpl isUserLoggedInSync];
}

- (void)getCurrentUser:(RCTPromiseResolveBlock)resolve 
                reject:(RCTPromiseRejectBlock)reject {
  [_swiftImpl getCurrentUser:resolve reject:reject];
}

- (void)login:(NSString *)email 
     password:(NSString *)password
      resolve:(RCTPromiseResolveBlock)resolve 
       reject:(RCTPromiseRejectBlock)reject {
  [_swiftImpl login:email password:password resolve:resolve reject:reject];
}

- (void)logout:(RCTPromiseResolveBlock)resolve 
        reject:(RCTPromiseRejectBlock)reject {
  [_swiftImpl logout:resolve reject:reject];
}

@end
#endif

Step 4: Usage in JavaScript

import React, { useState, useEffect } from 'react';
import { View, Text, Button } from 'react-native';
import AuthModule from './specs/NativeAuthModule';

function App() {
  const [user, setUser] = useState(null);

  // Sync call - no await needed, instant result
  // This is only possible with bridgeless TurboModules!
  const isLoggedIn = AuthModule.isUserLoggedIn();

  useEffect(() => {
    if (isLoggedIn) {
      loadUser();
    }
  }, []);

  const loadUser = async () => {
    const userData = await AuthModule.getCurrentUser();
    setUser(userData);
  };

  const handleLogin = async () => {
    try {
      await AuthModule.login('user@example.com', 'password123');
      loadUser();
    } catch (error) {
      console.error('Login failed:', error);
    }
  };

  const handleLogout = async () => {
    await AuthModule.logout();
    setUser(null);
  };

  return (
    <View style={{ padding: 20 }}>
      <Text>Logged in: {isLoggedIn ? 'Yes' : 'No'}</Text>

      {user ? (
        <>
          <Text>Welcome, {user.name}!</Text>
          <Button title="Logout" onPress={handleLogout} />
        </>
      ) : (
        <Button title="Login" onPress={handleLogin} />
      )}
    </View>
  );
}

Performance Measurement

// Measure the difference yourself
const measurePerformance = () => {
  // Sync method (bridgeless)
  const syncStart = performance.now();
  for (let i = 0; i < 1000; i++) {
    AuthModule.isUserLoggedIn();
  }
  const syncTime = performance.now() - syncStart;
  console.log(`1000 sync calls: ${syncTime.toFixed(2)}ms`);
  console.log(`Per call: ${(syncTime / 1000).toFixed(4)}ms`);

  // You'll see something like:
  // 1000 sync calls: 45.23ms
  // Per call: 0.0452ms
};

When to Use Sync vs Async Methods

✅ Use Sync Methods For:

Login status checks - needed immediately for UI rendering
Feature flags - instant access to cached values
User preferences - theme, language settings
Animation frame data - time-critical calculations

❌ Use Async Methods For:

API calls - network requests should never block JS
File operations - disk I/O is slow
Database queries - even SQLite should be async
Heavy computations - offload to background thread

Rule of Thumb

If it takes more than 1ms, make it async.

Common Gotchas

1. Forgetting `requiresMainQueueSetup`

// ❌ Wrong - sync methods won't work
+ (BOOL)requiresMainQueueSetup {
  return YES;
}

// ✅ Correct
+ (BOOL)requiresMainQueueSetup {
  return NO;
}

2. Missing `getTurboModule` Implementation

Without this, your module won't use bridgeless mode:

// ✅ Required for bridgeless
- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
    (const facebook::react::ObjCTurboModule::InitParams &)params {
  return std::make_shared<facebook::react::NativeAuthModuleSpecJSI>(params);
}

3. Not Running Codegen

After adding/changing your spec, regenerate native code:

cd ios && pod install

4. Using `.m` Instead of `.mm`

TurboModules require Objective-C++ for C++ interop:

❌ AuthModule.m
✅ AuthModule.mm

Verifying Bridgeless Mode Is Active

// Check if your module is loaded as TurboModule
import { TurboModuleRegistry } from 'react-native';

const module = TurboModuleRegistry.get('AuthModule');
console.log('TurboModule loaded:', module !== null);

// If this returns null, you're still on the old bridge

Summary

Feature	Old Bridge	0.73 TurboModule	0.74+ Bridgeless
Interop Proxy	N/A	Yes	No
Sync Methods	No	Yes (with overhead)	Yes (direct)
Serialization	JSON	Partial	None
Typical Latency	5-10ms	0.5-1ms	0.05ms

React Native 0.74+ with bridgeless mode gives you the best of both worlds: the developer experience of JavaScript with near-native performance for critical paths.

The isUserLoggedIn() sync method we built runs in ~0.05ms - that's 100x faster than the old bridge. For UI-critical operations like checking auth state before rendering, this makes a real difference.

Resources

Building an MCP Server: How We Connected DiskCleanKit to AI Assistants

Nam Tran — Fri, 02 Jan 2026 08:51:55 +0000

Introduction

In my previous article, I explained what Model Context Protocol (MCP) is — the "USB-C for AI" that provides a universal way to connect AI assistants to external tools and applications.

Today, I'm excited to share how we implemented MCP in DiskCleanKit 5.0, allowing AI assistants like Claude, Cursor, and VS Code Copilot to scan and clean your Mac automatically.

What you'll learn:

How MCP works under the hood
Step-by-step guide to building your own MCP server
Real-world implementation patterns
Publishing to npm and MCP Registry

Resources:

📦 npm: @vannamtran/diskcleankit-mcp
🔗 GitHub: namtran/diskcleankit-mcp
📋 MCP Registry: registry.modelcontextprotocol.io

What is MCP? (Quick Recap)

MCP (Model Context Protocol) is an open-source standard created by Anthropic that allows AI assistants to interact with external tools, data sources, and applications.

┌─────────────────────────────────────────────────────────────────┐
│                    Before MCP                                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   Claude ──── Custom Code ──── Your App                         │
│   ChatGPT ─── Different Code ── Your App                        │
│   Copilot ─── Another Code ──── Your App                        │
│                                                                 │
│   😫 Every AI needs custom integration                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                    After MCP                                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   Claude ────┐                                                  │
│   Cursor ────┼──── MCP Server ──── Your App                     │
│   Copilot ───┘                                                  │
│                                                                 │
│   😊 One integration works with all AI assistants               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

DiskCleanKit MCP Architecture

Here's how our MCP server connects AI assistants to DiskCleanKit:

┌─────────────────────────────────────────────────────────────────┐
│                    DiskCleanKit MCP Flow                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   User: "Clean up my Mac"                                       │
│            │                                                    │
│            ▼                                                    │
│   ┌─────────────────┐                                           │
│   │  AI Assistant   │  (Claude, Cursor, Copilot)                │
│   │  Understands    │                                           │
│   │  user intent    │                                           │
│   └────────┬────────┘                                           │
│            │ Calls MCP tool: one_touch_clean                    │
│            ▼                                                    │
│   ┌─────────────────┐                                           │
│   │   MCP Server    │  (@vannamtran/diskcleankit-mcp)           │
│   │   Node.js       │                                           │
│   └────────┬────────┘                                           │
│            │ URL Scheme: diskcleankit://one-touch-clean         │
│            ▼                                                    │
│   ┌─────────────────┐                                           │
│   │  DiskCleanKit   │  (macOS App)                              │
│   │  Native App     │                                           │
│   └────────┬────────┘                                           │
│            │ Writes result to temp file                         │
│            ▼                                                    │
│   ┌─────────────────┐                                           │
│   │  Response JSON  │  /tmp/diskcleankit_mcp_response.json      │
│   └────────┬────────┘                                           │
│            │                                                    │
│            ▼                                                    │
│   AI: "I cleaned 2.5GB of cache files from your Mac! 🎉"        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Step-by-Step: Building an MCP Server

Step 1: Project Setup

mkdir my-mcp-server
cd my-mcp-server
npm init -y

Install dependencies:

npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node

package.json:

{
  "name": "@yourname/my-mcp-server",
  "version": "1.0.0",
  "type": "module",
  "bin": {
    "my-mcp-server": "./dist/index.js"
  },
  "files": ["dist"],
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0",
    "zod": "^3.22.0"
  },
  "devDependencies": {
    "typescript": "^5.3.0",
    "@types/node": "^20.0.0"
  }
}

tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "declaration": true
  },
  "include": ["src/**/*"]
}

Step 2: Create the MCP Server

src/index.ts:

#!/usr/bin/env node

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// Create server instance
const server = new McpServer({
  name: "my-mcp-server",
  version: "1.0.0",
});

// Define your tools
server.tool(
  "hello_world",
  "Says hello to the user",
  {
    name: z.string().describe("Name to greet"),
  },
  async ({ name }) => {
    return {
      content: [
        {
          type: "text",
          text: `Hello, ${name}! 👋`,
        },
      ],
    };
  }
);

// Start the server
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("MCP Server running on stdio");
}

main().catch(console.error);

Step 3: How DiskCleanKit Implements Tools

Here's how we implemented the actual tools in DiskCleanKit MCP:

// Tool: one_touch_scan
server.tool(
  "one_touch_scan",
  "Scan Mac for junk files without deleting anything",
  {},
  async () => {
    // 1. Trigger the app via URL scheme
    const { exec } = await import("child_process");
    exec("open 'diskcleankit://one-touch-scan'");

    // 2. Wait for response file
    const response = await waitForResponse();

    // 3. Return result to AI
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(response, null, 2),
        },
      ],
    };
  }
);

// Tool: one_touch_clean
server.tool(
  "one_touch_clean",
  "Scan AND clean junk files automatically (safe items only)",
  {},
  async () => {
    const { exec } = await import("child_process");
    exec("open 'diskcleankit://one-touch-clean'");

    const response = await waitForResponse();

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(response, null, 2),
        },
      ],
    };
  }
);

// Tool: get_disk_status
server.tool(
  "get_disk_status",
  "Check disk space and health status",
  {},
  async () => {
    const { exec } = await import("child_process");
    exec("open 'diskcleankit://disk-status'");

    const response = await waitForResponse();

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(response, null, 2),
        },
      ],
    };
  }
);

// Helper: Wait for app response
async function waitForResponse(timeout = 30000): Promise<any> {
  const responseFile = "/tmp/diskcleankit_mcp_response.json";
  const startTime = Date.now();

  while (Date.now() - startTime < timeout) {
    try {
      const fs = await import("fs/promises");
      const data = await fs.readFile(responseFile, "utf-8");
      await fs.unlink(responseFile); // Clean up
      return JSON.parse(data);
    } catch {
      // File not ready yet, wait and retry
      await new Promise((resolve) => setTimeout(resolve, 500));
    }
  }

  throw new Error("Timeout waiting for DiskCleanKit response");
}

Step 4: Communication via URL Schemes

The key to connecting Node.js MCP server to a native macOS app is URL schemes.

In your macOS app (Swift):

// Register URL scheme in Info.plist
// <key>CFBundleURLSchemes</key>
// <array><string>diskcleankit</string></array>

// Handle URL in AppDelegate
func application(_ application: NSApplication, 
                 open urls: [URL]) {
    guard let url = urls.first else { return }

    switch url.host {
    case "one-touch-scan":
        performScan()
    case "one-touch-clean":
        performClean()
    case "disk-status":
        getDiskStatus()
    default:
        break
    }
}

// Write response for MCP server
func writeResponse(_ result: [String: Any]) {
    let path = "/tmp/diskcleankit_mcp_response.json"
    let data = try? JSONSerialization.data(withJSONObject: result)
    try? data?.write(to: URL(fileURLWithPath: path))
}

Publishing Your MCP Server

Step 1: Build the Project

npm run build

Step 2: Add Shebang to Entry File

Make sure dist/index.js starts with:

#!/usr/bin/env node

Step 3: Publish to npm

npm login
npm publish --access public

Step 4: Register with MCP Registry

Create a server.json file:

{
  "$schema": "https://registry.modelcontextprotocol.io/schema/server.json",
  "name": "@vannamtran/diskcleankit-mcp",
  "description": "MCP server for DiskCleanKit - One Touch Scan and Clean for Mac",
  "repository": {
    "type": "git",
    "url": "https://github.com/namtran/diskcleankit-mcp"
  },
  "version_detail": {
    "version": "1.0.0",
    "release_date": "2025-01-01",
    "is_latest": true
  },
  "packages": [
    {
      "registry_name": "npm",
      "name": "@vannamtran/diskcleankit-mcp",
      "version": "1.0.0"
    }
  ],
  "tools": [
    {
      "name": "one_touch_scan",
      "description": "Scan Mac for junk files (safe, no deletion)"
    },
    {
      "name": "one_touch_clean",
      "description": "Scan AND clean junk files automatically"
    },
    {
      "name": "get_disk_status",
      "description": "Check disk space and health"
    }
  ]
}

Submit to the registry by creating a PR to github.com/modelcontextprotocol/registry.

Configuring AI Clients

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "diskcleankit": {
      "command": "npx",
      "args": ["@vannamtran/diskcleankit-mcp"]
    }
  }
}

Claude Code (CLI)

claude mcp add diskcleankit -- npx @vannamtran/diskcleankit-mcp

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "diskcleankit": {
      "command": "npx",
      "args": ["@vannamtran/diskcleankit-mcp"]
    }
  }
}

VS Code (GitHub Copilot)

Add to settings.json:

{
  "mcp.servers": {
    "diskcleankit": {
      "command": "npx",
      "args": ["@vannamtran/diskcleankit-mcp"]
    }
  }
}

Usage Examples

Once configured, you can ask your AI assistant:

User Says	AI Calls	Result
"Scan my Mac for junk"	`one_touch_scan`	Shows cleanable items
"Clean up my Mac"	`one_touch_clean`	Removes cache/logs
"How much disk space do I have?"	`get_disk_status`	Shows storage info
"What can be cleaned?"	`get_cleanable_estimate`	Estimates by category
"Show cleaning history"	`get_cleaning_history`	Past sessions

Example conversation:

User: My Mac is running low on storage. Can you help?

Claude: I'll check your disk status and scan for cleanable files.

[Calls get_disk_status]
[Calls one_touch_scan]

Your Mac has 45GB free out of 500GB. I found 8.2GB of cleanable 
files:
- System Caches: 3.1GB
- Application Caches: 2.8GB
- Browser Caches: 1.5GB
- Log Files: 0.8GB

Would you like me to clean these? They're all safe to remove and 
will be regenerated as needed.

User: Yes, please clean them.

Claude: [Calls one_touch_clean]

Done! I've cleaned 8.2GB of cache and log files. Your Mac now 
has 53.2GB free. 🎉

Security Considerations

When building MCP servers, security is crucial:

Practice	Description
Principle of Least Privilege	Only expose necessary tools
Safe by Default	`one_touch_scan` doesn't delete anything
Clear Tool Names	Users understand what each tool does
No External Data	All processing happens locally
Safe Items Only	Only clean regenerable files (caches, logs)

What DiskCleanKit MCP cleans:

Category	Safe?	Regenerable?
System Caches	✅ Yes	✅ Yes
Application Caches	✅ Yes	✅ Yes
Browser Caches	✅ Yes	✅ Yes
Log Files	✅ Yes	✅ Yes
Personal Documents	❌ Never touched	-
Photos/Videos	❌ Never touched	-

Common Patterns for MCP Servers

Pattern 1: URL Scheme (Desktop Apps)

MCP Server → URL Scheme → Native App → Temp File → MCP Server

Best for: macOS/Windows desktop applications

Pattern 2: Local HTTP API

MCP Server → HTTP Request → Local Server → HTTP Response

Best for: Apps with REST APIs

Pattern 3: IPC (Inter-Process Communication)

MCP Server → Named Pipe/Socket → Native Process

Best for: Background services

Pattern 4: Direct File System

MCP Server → Read/Write Files Directly

Best for: File management tools

Troubleshooting

"Timeout waiting for response"

# Check if DiskCleanKit is installed
ls /Applications/DiskCleanKit.app

# Try opening manually
open "diskcleankit://disk-status"

"Server not appearing in Claude"

Verify config path is correct
Restart Claude Desktop
Check logs: ~/Library/Logs/Claude/mcp*.log

"Permission denied"

# Make the script executable
chmod +x ./dist/index.js

What's Next?

MCP is still evolving. Here's what we're excited about:

More AI Clients: Expecting ChatGPT support soon
Remote MCP Servers: HTTP-based servers (not just stdio)
Richer Tool Types: Beyond just function calls
Better Discovery: Improved MCP Registry features

Conclusion

Building an MCP server is straightforward once you understand the pattern:

Create a Node.js server using @modelcontextprotocol/sdk
Define tools that AI assistants can call
Connect to your app via URL schemes, HTTP, or IPC
Publish to npm and register with MCP Registry
Configure AI clients with a simple JSON config

MCP opens up exciting possibilities for AI-powered applications. Your desktop app can now be controlled by natural language through any MCP-compatible AI assistant.

Try it yourself:

npm install -g @vannamtran/diskcleankit-mcp

Resources

📦 npm Package: @vannamtran/diskcleankit-mcp
🔗 GitHub: namtran/diskcleankit-mcp
📋 MCP Registry: registry.modelcontextprotocol.io
📖 MCP Documentation: modelcontextprotocol.io
🧹 DiskCleanKit App: diskcleankit.com

Have you built an MCP server? Share your experience in the comments!

Tags: #mcp #ai #typescript #macos #tutorial

Understanding MCP: The Universal Protocol Connecting AI to Your World

Nam Tran — Sun, 28 Dec 2025 11:35:07 +0000

What is Model Context Protocol (MCP)?

Model Context Protocol (MCP) is an open-source standard that's revolutionizing how AI applications connect to the world around them. Think of it as the USB-C for AI — just as USB-C provides a universal way to connect devices, MCP provides a standardized way to connect AI assistants to external tools, data sources, and applications.

Image source: modelcontextprotocol.io

Before MCP, every AI integration required custom code. Want Claude to access your files? Write custom code. Want ChatGPT to query your database? More custom code. MCP changes this by providing a universal protocol that works across all AI applications and all data sources.

Why MCP Matters

The Problem MCP Solves

Traditional AI assistants are limited to what they know from training data. They can't:

Access your local files
Query your databases
Control your applications
Interact with real-time data

MCP breaks down these barriers by creating a standardized bridge between AI and external systems.

Key Benefits

Benefit	Description
Universal Compatibility	One protocol works with Claude, ChatGPT, and other AI assistants
Reduced Development Time	No more custom integrations for each AI service
Enhanced AI Capabilities	AI can now access real data and take real actions
Secure by Design	Built-in security and permission models

How MCP Works

MCP follows a simple client-server architecture:

Core Components

MCP Clients — AI applications (like Claude, ChatGPT) that consume services
MCP Servers — Applications that expose data, tools, and workflows
Transport Layer — Communication channels (stdio, HTTP streaming)

What MCP Can Provide

Component	Description	Example
Tools	Functions AI can call	Run scripts, search files, execute commands
Resources	Data AI can access	File contents, database records, API responses
Prompts	Specialized instructions	Domain-specific templates and workflows
Sampling	Model interaction requests	Context-aware suggestions and completions

Real-World Applications

1. Personalized AI Assistants

AI can access your calendar, notes, and files to provide truly personalized help. Imagine an AI that knows your schedule, your projects, and can help you manage your day.

2. Design-to-Code Workflows

Claude Code can generate entire web applications by connecting to Figma designs through MCP, transforming visual designs into working code.

3. Enterprise Data Analysis

Organizations can connect AI chatbots to multiple databases, enabling natural language queries across all company data.

4. Smart Home & IoT

AI can create 3D designs and send them directly to 3D printers, control smart home devices, and interact with the physical world.

The MCP Registry

The MCP Registry serves as a central directory for discovering MCP servers. It's a metaregistry that hosts metadata about available servers rather than the actual code.

Finding MCP Servers

The registry helps you discover:

Community servers — Built by developers worldwide
Official servers — From Anthropic and partners
Industry-specific tools — For various domains

Deployment Options

Method	Description
Package-based	NPM, PyPI, Docker containers
Remote Services	Streamable HTTP endpoints
Hybrid	Combination of local and remote

Security & Authentication

MCP takes security seriously with:

Namespace verification — Servers are verified via GitHub OAuth or DNS
Permission models — Fine-grained control over what AI can access
Audit logging — Track all AI interactions with your data

Getting Started with MCP

For Developers

Explore the Registry — Visit modelcontextprotocol.io to discover available servers
Build a Server — Create MCP servers to expose your tools and data
Build a Client — Develop applications that connect to MCP servers

Quick Example: Creating an MCP Server

Here's a simple example of what an MCP server structure looks like:

import { Server } from "@modelcontextprotocol/sdk/server";

const server = new Server({
  name: "my-mcp-server",
  version: "1.0.0",
});

// Define a tool
server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "search_files",
      description: "Search for files in the filesystem",
      inputSchema: {
        type: "object",
        properties: {
          query: { type: "string", description: "Search query" },
        },
        required: ["query"],
      },
    },
  ],
}));

// Handle tool calls
server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "search_files") {
    // Implement your search logic here
    return { content: [{ type: "text", text: "Search results..." }] };
  }
});

For Users

Enable MCP in your AI app — Claude Desktop and other apps support MCP
Install MCP servers — Add servers for the tools you need
Enjoy enhanced AI — Your AI assistant can now do more

The Future of AI Integration

MCP represents a fundamental shift in how we interact with AI. Instead of AI being a separate tool, it becomes integrated into our entire digital workflow. The protocol is:

Open Source — Community-driven development
Extensible — Easy to add new capabilities
Growing — Ecosystem expanding rapidly

Community & Support

MCP is maintained by key contributors from Anthropic, GitHub, and the open-source community. Development happens through:

GitHub Repository
Discord community
Regular updates and improvements

Useful Resources

Official Documentation: modelcontextprotocol.io
MCP Registry: registry.modelcontextprotocol.io
GitHub: github.com/modelcontextprotocol
Specification: spec.modelcontextprotocol.io

Conclusion

MCP is changing how we build AI-powered applications. By providing a universal protocol for AI-to-world communication, it's making AI assistants more capable, more useful, and more integrated into our daily workflows.

Whether you're a developer looking to expose your tools to AI, or a user wanting to enhance your AI assistant's capabilities, MCP opens up exciting new possibilities.

Have you tried building with MCP? Share your experiences in the comments!

What MCP servers are you most excited about? Let me know in the comments below!

Update: We're excited to announce that DiskCleanKit will support MCP in the near future, bringing AI-powered intelligent cleaning recommendations to your Mac!

Automate Your Mac Cleanup: Introducing DiskCleanKit 4.0 with Scheduled Scans, Alerts & URL Schemes

Nam Tran — Tue, 23 Dec 2025 05:38:36 +0000

DiskCleanKit 4.0 brings powerful automation features to Mac cleanup - scheduled scans, low disk space alerts, and URL schemes for Terminal/Shortcuts integration. Perfect for developers who want hands-free Mac maintenance.

The Problem: Manual Cleanup Doesn't Scale

As developers, our Macs accumulate junk at an alarming rate:

Xcode derived data eating 50GB+ silently
npm/node_modules scattered across projects
Docker images you forgot to prune
Simulator caches from iOS development
Build artifacts from various IDEs

Most of us remember to clean up only when that dreaded "Disk Full" notification appears - usually at the worst possible time (mid-compile, anyone?).

What if your Mac could maintain itself?

Introducing DiskCleanKit 4.0 Automation

After months of development and community feedback, I'm excited to announce DiskCleanKit 4.0 - now with comprehensive automation support.

What's New in 4.0

Scheduled Scans & Auto-Clean - Set it and forget it
Low Disk Space Alerts - Get warned before it's critical
Auto Startup - Always monitoring in the background
URL Schemes - Full Terminal & Shortcuts integration
Finder Integration - Right-click context menu actions

Let's dive into each feature.

1. Scheduled Scans: Your Mac on Autopilot

Configure automatic scans on your preferred schedule:

Frequency	Best For
Daily	Active developers (recommended)
Weekly	Light users
2 Weekly	Moderate use
Monthly	Minimal maintenance

Setup

Open DiskCleanKit → Preferences → Automation
Enable "Scheduled Scan"
Choose frequency and scan type (Quick Clean, Deep Scan, or One-Touch)
Optionally enable "Auto Clean After Scan"

Now your Mac cleans itself while you focus on coding.

2. Low Disk Space Alerts: Never Get Caught Off Guard

Set a threshold and receive notifications before your disk fills up:

Recommended thresholds:
- 256GB SSD → Alert at 10GB remaining
- 512GB SSD → Alert at 20GB remaining
- 1TB+ SSD  → Alert at 50GB remaining

This gives you time to clean up before Xcode refuses to build or Docker can't pull images.

3. URL Schemes: The Developer's Power Feature

This is where it gets interesting. DiskCleanKit 4.0 supports URL schemes for complete automation control.

Available Schemes

diskcleankit://onetouch     # One-Touch Clean mode
diskcleankit://quickclean   # Quick Clean scan
diskcleankit://deepscan     # Deep Scan
diskcleankit://duplicates   # Duplicate Finder
diskcleankit://uninstaller  # App Uninstaller

Parameters

Parameter	Description
`autoscan=true`	Start scanning immediately
`autoclean=true`	Auto-clean after scan

Terminal Examples

# Quick cleanup before a big build
open "diskcleankit://quickclean?autoscan=true&autoclean=true"

# Full deep scan with auto-clean
open "diskcleankit://deepscan?autoscan=true&autoclean=true"

# One-touch mode - scan and clean everything
open "diskcleankit://onetouch?autoscan=true&autoclean=true"

Real-World Automation Recipes

Recipe 1: Pre-Build Cleanup Script

Add this to your build scripts to ensure you always have space:

#!/bin/bash
# pre-build-cleanup.sh

# Check available space (in GB)
available=$(df -g / | awk 'NR==2 {print $4}')

if [ "$available" -lt 20 ]; then
    echo "Low disk space detected. Running cleanup..."
    open "diskcleankit://quickclean?autoscan=true&autoclean=true"
    sleep 30  # Wait for cleanup
fi

# Continue with build
xcodebuild ...

Recipe 2: macOS Shortcuts Automation

Create a Shortcut that runs cleanup every time you close Xcode:

Open Shortcuts app
Go to Automation tab
Create automation: "When Xcode closes"
Add action: Run Shell Script
Enter: open "diskcleankit://quickclean?autoscan=true&autoclean=true"

Recipe 3: Cron Job for Nightly Cleanup

# Add to crontab (crontab -e)
# Run deep scan every night at 2 AM
0 2 * * * open "diskcleankit://deepscan?autoscan=true&autoclean=true"

Recipe 4: Alfred/Raycast Integration

Create a workflow/script command:

# Quick Clean shortcut
open "diskcleankit://onetouch?autoscan=true&autoclean=true"

Now trigger a full cleanup with a keyboard shortcut.

Recipe 5: Git Hook - Clean Before Large Operations

#!/bin/bash
# .git/hooks/pre-rebase

# Ensure enough space before rebase
open "diskcleankit://quickclean?autoscan=true&autoclean=true"
sleep 10

Finder Integration: Clean Files Where You Find Them

DiskCleanKit 4.0 also adds right-click context menu options directly in Finder:

Quick Clean Folder - Clean junk in any folder
Scan for Duplicates - Find duplicates within a folder
Find Large Files - Identify space hogs
Analyze Storage - See what's using space

Enable Finder Integration

System Settings → Login Items & Extensions
Find DiskCleanKit → File Provider
Enable it

Now right-click any folder to access cleanup options instantly.

What DiskCleanKit Cleans

For those wondering what actually gets cleaned:

System Junk

System caches and logs
Temporary files
Broken symlinks
Old iOS backups

Developer-Specific

Xcode derived data & archives
CocoaPods cache
Carthage build folder
npm/yarn cache
pip cache
Homebrew cache
Docker unused images (manual)

Application Caches

Browser caches (Safari, Chrome, Firefox)
App caches and temp files
Mail downloads
Old app support files

Privacy & Security

A note on privacy since I know developers care about this:

No data collection - Everything stays on your Mac
No account required - Works completely offline
No analytics - We don't track what you clean
Sandboxed - Mac App Store approved, follows Apple's security guidelines
Transparent - Always shows what will be deleted before cleaning

Getting Started

DiskCleanKit 4.0 is available now on the Mac App Store.

Download: DiskCleanKit on Mac App Store

Website: diskcleankit.com

Quick Start for Developers

Install from Mac App Store
Run your first scan (One-Touch mode recommended)
Enable Automation in Preferences
Set up your preferred URL scheme workflows
Enjoy a self-maintaining Mac

Conclusion

DiskCleanKit 4.0 transforms Mac cleanup from a manual chore into an automated background task. Whether you prefer scheduled scans, Terminal commands, or Shortcuts integration, there's an automation method that fits your workflow.

No more "Disk Full" surprises. No more manual cleanup sessions. Just a Mac that maintains itself while you focus on what matters - writing code.

What automation workflows would you create? Drop a comment below or reach out on Twitter. I'm always looking for ways to make DiskCleanKit more useful for developers.

How to Set Up and Use DiskCleanKit Widgets on Your Mac

Nam Tran — Fri, 12 Dec 2025 00:14:00 +0000

DiskCleanKit widgets let you monitor your Mac’s storage and system health without opening the full app.
They’re perfect for:

Quick glances at available storage
Real-time monitoring of RAM and CPU
One-click access to cleaning functions

Adding Desktop Widgets

Step 1: Access Widget Gallery

Right-click on any empty space on your desktop.
Select Edit Widgets from the context menu.
Or click the date/time in your menu bar and select Edit Widgets.

You’ll now see the Widget Gallery window open.

Step 2: Find DiskCleanKit Widgets

In the widget gallery, search for “DiskCleanKit”.
You’ll see several widget options available in different sizes.

Step 3: Choose Your Widget Size

Small Widget

Shows free and used storage percentage
Minimal footprint on your desktop

Medium Widget

Displays storage breakdown with a visual chart
Shows RAM usage
Includes a Quick Scan button

Large Widget

Full storage visualization
RAM and CPU monitoring
One Touch Clean button
Quick access to Disk Manager

Step 4: Add to Desktop

Drag your chosen widget to your desktop.
Position it where you want.
Click Done when finished.

Your DiskCleanKit widget is now live on your desktop, ready to keep your Mac in check at a glance.

Menu Bar Widget

The menu bar widget is enabled by default when you install DiskCleanKit.
You’ll see the DiskCleanKit icon appear in your menu bar immediately.

If you want to hide it, go to Menu → Hide Menu Bar Widget.

Menu Bar Features

Click to see a quick storage summary
One-click access to One Touch Clean
Open the full app instantly

Using Widget Actions

One Touch Clean from Widget

Click the Clean button on your widget.
DiskCleanKit performs a quick, safe clean.
The widget updates to show your new free space.
No need to open the full app!

Opening Disk Manager

Click the disk icon on medium or large widgets.
The Disk Manager opens directly, allowing you to manage all drives efficiently.

Tips for Widget Users

Place widgets strategically – Put them where you’ll notice them during work.
Use multiple widgets – Different sizes can serve different purposes.
Check before large tasks – Glance at storage before downloading big files.

Troubleshooting

Widget Not Updating

Check if DiskCleanKit has the necessary permissions.
Try removing and re-adding the widget.
Restart the app.

Widget Not Appearing in Gallery

Make sure you have the latest version of DiskCleanKit.
Ensure you’re running macOS 13 or later.
Restart your Mac if needed.

Final Thoughts

Widgets make Mac maintenance effortless.
Set them up once and enjoy continuous, real-time visibility into your Mac’s health — no app window required.

Stay clean, stay fast, and make the most of your Mac with DiskCleanKit.

Download DiskCleanKit