Merge branch 'master' of https://github.com/AndrewClements84/PromptStream.AI

Author: AndrewMorgan1

README.md

@@ -2,102 +2,148 @@
   <img src="https://github.com/AndrewClements84/PromptStream.AI/blob/master/assets/logo.png?raw=true" alt="PromptStream.AI" width="500"/>
 </p>
 
-<h1 align="center">PromptStream.AI CLI</h1>
+# 🧠 PromptStream.AI
 
-<p align="center">
-  <b>Build, validate, and analyze prompt flows — directly from your terminal.</b><br/>
-  <i>Part of the Flow.AI ecosystem alongside TokenFlow.AI and Flow.AI.Core.</i>
-</p>
-
-<p align="center">
-  <a href="https://www.nuget.org/packages/PromptStream.AI.CLI"><img src="https://img.shields.io/nuget/v/PromptStream.AI.CLI.svg" alt="NuGet version"></a>
-  <a href="https://github.com/AndrewClements84/PromptStream.AI/actions/workflows/dotnet.yml"><img src="https://github.com/AndrewClements84/PromptStream.AI/actions/workflows/dotnet.yml/badge.svg" alt="Build status"></a>
-  <a href="https://codecov.io/gh/AndrewClements84/PromptStream.AI"><img src="https://codecov.io/gh/AndrewClements84/PromptStream.AI/branch/master/graph/badge.svg" alt="Coverage"></a>
-  <a href="https://buymeacoffee.com/andrewclements84"><img src="https://img.shields.io/badge/☕-Buy%20me%20a%20coffee-ffdd00?logo=buymeacoffee&logoColor=black" alt="Buy me a coffee"></a>
-</p>
+[![Build](https://github.com/AndrewClements84/PromptStream.AI/actions/workflows/dotnet.yml/badge.svg)](https://github.com/AndrewClements84/PromptStream.AI/actions/workflows/dotnet.yml)
+[![Docs](https://img.shields.io/badge/docs-online-brightgreen.svg?logo=githubpages)](https://andrewclements84.github.io/PromptStream.AI/)
+[![NuGet Version](https://img.shields.io/nuget/v/PromptStream.AI.svg?logo=nuget&cacheSeconds=60)](https://www.nuget.org/packages/PromptStream.AI)
+[![NuGetDownloads](https://img.shields.io/nuget/dt/PromptStream.AI.svg)](https://www.nuget.org/packages/PromptStream.AI)
+[![Coverage](https://codecov.io/gh/AndrewClements84/PromptStream.AI/branch/master/graph/badge.svg)](https://codecov.io/gh/AndrewClements84/PromptStream.AI)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Buy Me A Coffee](https://img.shields.io/badge/☕%20Buy%20me%20a%20coffee-FFDD00?style=flat&logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/andrewclements84)
 
 ---
 
-## 🚀 Installation
+### 🧩 Description
+**PromptStream.AI** — Token-aware prompt composition, validation, and conversational context toolkit for .NET.
 
-Install globally via the .NET CLI:
+Built atop [Flow.AI.Core](https://github.com/AndrewClements84/Flow.AI.Core) and [TokenFlow.AI](https://github.com/AndrewClements84/TokenFlow.AI),  
+PromptStream.AI enables developers to **compose**, **validate**, **generate**, and **manage** multi-turn AI prompts with token budgeting, interpolation, and contextual memory.
 
-```bash
-dotnet tool install --global promptstream.ai.cli
-```
+---
 
-Once installed, you can call it from anywhere using the `promptstream` command.
+### ⚙️ Key Features
+- 🧩 **Token-aware prompt builder** with variable interpolation (`{{variable}}` syntax)
+- ✅ **Validation engine** for token limits, structure, and completeness
+- 💬 **Shared Core Models** from Flow.AI.Core (`PromptTemplate`, `PromptInstance`, `PromptMessage`, `PromptResponse`)
+- 🧠 **Context manager** with replay, merge, summarization, and JSON persistence
+- 💾 **Persistent context storage** (`ToJson` / `LoadFromJson`)
+- 🧮 **Token budgeting tools** (`EstimateTokenUsage`, `TrimToTokenBudget`)
+- ⚡ **CLI utility (`PromptStream.AI.CLI`)** for building, validating, analyzing, and generating prompts
+- 🔌 Seamless integration with **TokenFlow.AI** for model-aware tokenization
 
 ---
 
-## ⚙️ Usage Examples
-
-### 🧱 Build a prompt
-Render a template and substitute variables:
+### 🚀 Installation
 
 ```bash
-promptstream build --template "Hello {{name}}" --var name=Andrew
+dotnet add package PromptStream.AI
 ```
 
-Output:
-```
-✅ Prompt built successfully:
+Requires:
+- .NET 8.0 or higher  
+- Flow.AI.Core v0.2.0+  
+- (optional) TokenFlow.AI for advanced token metrics  
 
-Hello Andrew
+---
+
+### 🧠 Quickstart Example
+
+```csharp
+using System;
+using System.Collections.Generic;
+using Flow.AI.Core.Models;
+using Flow.AI.Core.Interfaces;
+using TokenFlow.AI.Integration;
+using PromptStream.AI.Services;
+
+// Initialize the service with token tracking
+var tokenProvider = new BasicTokenFlowProvider();
+var modelClient = new TokenFlowModelClient("gpt-4o-mini");
+var context = new PromptContextManager();
+
+var service = new PromptStreamService(tokenProvider, context, modelClient);
+
+// Define a shared Core template
+var template = new PromptTemplate
+{
+    Id = "summarize-v1",
+    Template = "Summarize the following:\n\n{{input}}\n\nBe concise.",
+    RequiredVariables = new() { "input" }
+};
+
+// Variables to inject
+var variables = new Dictionary<string, string>
+{
+    ["input"] = "Flow.AI enables composable AI workflows for .NET developers."
+};
+
+// Build and validate
+var (instance, validation) = service.BuildAndValidate(template, variables);
+
+if (validation.IsValid)
+{
+    Console.WriteLine($"✅ Valid prompt ({validation.TokenCount} tokens)");
+    Console.WriteLine(instance.RenderedText);
+}
+else
+{
+    Console.WriteLine($"❌ Invalid: {string.Join(", ", validation.Errors)}");
+}
+
+// Add a user message to the context
+context.AddMessage(new PromptMessage { Role = "user", Content = instance.RenderedText });
 ```
 
-### 🔍 Validate a prompt
-Check structure and token limits:
+---
+
+### 💻 CLI Usage (`PromptStream.AI.CLI`)
+
+PromptStream.AI includes a full command-line interface for developers to build, validate, analyze, and generate prompts directly from the terminal.
 
+#### 🧩 Build a prompt
 ```bash
-promptstream validate --template "Summarize this text: {{content}}" --var content="PromptStream.AI is awesome"
+dotnet run --project src/PromptStream.AI.CLI/PromptStream.AI.CLI.csproj -- build --template "Hello {{name}}" --var name=Andrew
 ```
 
-### 📊 Analyze cost and tokens
-Estimate model usage and pricing:
-
+#### ✅ Validate a prompt
 ```bash
-promptstream analyze --template "Explain quantum computing in simple terms."
+dotnet run --project src/PromptStream.AI.CLI/PromptStream.AI.CLI.csproj -- validate --template "Summarize {{topic}}" --var topic="AI in .NET"
 ```
 
-### 💬 Generate a model response
-Build, validate, and request a completion from your configured provider:
-
+#### 🤖 Generate a model response
 ```bash
-promptstream generate --template "Write a haiku about AI" --save context.json
+dotnet run --project src/PromptStream.AI.CLI/PromptStream.AI.CLI.csproj -- generate --template "Explain {{concept}}" --var concept="tokenization" --save context.json
 ```
 
-### 🧠 Manage context
-Inspect or clear your conversation history:
-
+#### 🧠 Manage conversation context
 ```bash
-promptstream context --load context.json --summarize
+dotnet run --project src/PromptStream.AI.CLI/PromptStream.AI.CLI.csproj -- context --load context.json --summarize
 ```
 
----
-
-## 🧩 Features
+#### 📊 Analyze prompt usage
+```bash
+dotnet run --project src/PromptStream.AI.CLI/PromptStream.AI.CLI.csproj -- analyze --template "Summarize {{topic}}" --var topic="AI" --model gpt-4o-mini
+```
 
-- 🧠 **Prompt orchestration** — consistent Flow.AI.Core integration  
-- 🧪 **Validation & analysis** — token counts, cost estimation, structure checks  
-- ⚙️ **Developer-first CLI** — clean UX, global tool packaging, colorful output  
-- 🤝 **Ecosystem-ready** — interoperable with TokenFlow.AI and Flow.AI.Core  
+**Available commands:**
+| Command | Description |
+|----------|--------------|
+| `build` | Render a prompt with variable substitution |
+| `validate` | Validate prompt completeness and token limits |
+| `generate` | Build, validate, and produce a model-like response |
+| `context` | Load, save, summarize, or clear conversation context |
+| `analyze` | Estimate token usage and cost for prompts |
 
 ---
 
-## 🗺️ Documentation
-
-👉 [CLI Usage Guide](https://andrewclements84.github.io/PromptStream.AI/docs/cli-usage.html)
+### 🌟 Supporting the Project
 
-For full developer docs:
-[PromptStream.AI Documentation](https://andrewclements84.github.io/PromptStream.AI)
+If you find **PromptStream.AI** helpful, please consider  
+⭐ **starring the repository** and ☕ [**supporting my work**](https://buymeacoffee.com/andrewclements84).  
+Your support helps keep the Flow.AI ecosystem growing.
 
 ---
 
-## 🧑‍💻 Author & License
-
-**Author:** [AndrewClements84](https://github.com/AndrewClements84)  
-**License:** MIT  
-**Project:** [PromptStream.AI on GitHub](https://github.com/AndrewClements84/PromptStream.AI)
-
----
+> Part of the **Flow.AI Ecosystem**  
+> © 2025 Andrew Clements