TalkPipe 0.12.2__tar.gz → 0.12.3__tar.gz

{talkpipe-0.12.2 → talkpipe-0.12.3}/.github/copilot-instructions.md

@@ -1,6 +1,18 @@
 # TalkPipe AI Coding Instructions
 
-*Cursor users: See [AGENTS.md](../AGENTS.md) and `.cursor/skills/` for additional workflows (TDD, changelog, doc examples, entry points).*
+*Cursor users: See [AGENTS.md](../AGENTS.md) and `.cursor/skills/` for additional workflows.*
+
+## Quick Actions (Prompts)
+
+Use these slash commands in VS Code chat (type `/` to invoke):
+
+| Prompt | When to use |
+|--------|-------------|
+| `/tdd` | Implement a change with write-fail-fix-pass TDD order |
+| `/add-segment` | Add a new segment or source end-to-end (test → impl → entry-point → changelog) |
+| `/changelog` | Update CHANGELOG.md after a feature or fix |
+| `/update-entry-points` | Regenerate pyproject.toml entry points from decorators |
+| `/doc-examples` | Validate and fix documentation code examples |
 
 ## Project Overview
 

talkpipe-0.12.3/.github/prompts/add-segment.prompt.md

@@ -0,0 +1,57 @@
+---
+mode: agent
+description: Add a new segment or source to TalkPipe. Use when creating new pipe components. Covers decorator pattern, parameter annotations, entry-point registration, and TDD.
+---
+
+Add a new **$input** to TalkPipe following all project conventions:
+
+## Step 1 — Write a failing test
+
+In the appropriate file under `tests/talkpipe/`, write a test that fails without the new component. Run it to confirm failure:
+
+```bash
+source .venv/bin/activate && pytest <test-file> -v
+```
+
+## Step 2 — Implement the component
+
+Place it in the appropriate module under `src/talkpipe/`:
+
+```python
+from typing import Annotated, Iterator, Any
+from talkpipe.pipe.core import segment, field_segment
+from talkpipe import register_segment  # or register_source
+
+@register_segment("mySegment")          # camelCase name used in ChatterLang
+@segment()
+def my_segment(
+    items: Iterator[Any],
+    param: Annotated[str, "Description of this parameter"] = "default",
+) -> Iterator[Any]:
+    for item in items:
+        yield item  # process and yield
+```
+
+Rules:
+- Use `@segment()` for iterators; `@field_segment()` for per-field transforms
+- Use `Annotated[type, "description"]` for every parameter (shown in ChatterLang reference)
+- Do NOT add docstrings documenting parameters — use `Annotated` instead
+- For `@field_segment`, the first non-items argument is the `field` parameter by convention
+
+## Step 3 — Register entry point
+
+```bash
+.venv/bin/python .cursor/skills/update-entry-points/scripts/update_entry_points.py
+```
+
+Verify the new entry appears in `pyproject.toml` under `[project.entry-points."talkpipe.segments"]` or `"talkpipe.sources"`.
+
+## Step 4 — Verify test passes
+
+```bash
+pytest <test-file> -v
+```
+
+## Step 5 — Update CHANGELOG.md
+
+Add a bullet under `## Unreleased` describing the new component.

talkpipe-0.12.3/.github/prompts/changelog.prompt.md

@@ -0,0 +1,23 @@
+---
+mode: agent
+description: Update CHANGELOG.md after implementing a feature, fixing a bug, or making any user-facing change. Handles update-vs-add logic correctly.
+---
+
+Update [CHANGELOG.md](../../CHANGELOG.md) under the `## Unreleased` section.
+
+**Decision logic:**
+1. Is this a **minor change to an existing feature** already mentioned in Unreleased?
+   - Yes → Update that existing bullet; do not add a new one
+   - No → Add a new bullet at the top of the Unreleased list
+
+2. Is this **purely internal** (refactor, no user impact)?
+   - Yes → Changelog update optional
+   - No → Always update
+
+**Format rules:**
+- Present tense, sentence case
+- Use backticks for segment/command names (e.g. `mySegment`, `run_doc_examples`)
+- Link to docs with `[text](path)` when helpful
+- Multi-line bullets use 2-space indent for continuation lines
+
+The change to document: $input

talkpipe-0.12.3/.github/prompts/doc-examples.prompt.md

@@ -0,0 +1,29 @@
+---
+mode: agent
+description: Validate and fix documentation code examples. Use after editing docs, before committing doc changes, or when examples may be broken. Runs examples via pytest and fixes formatting issues.
+---
+
+Validate documentation code examples following TalkPipe conventions. See [docs/architecture/documentation-formatting.md](../../docs/architecture/documentation-formatting.md) for full formatting rules.
+
+## Run examples via pytest
+
+```bash
+source .venv/bin/activate
+pytest tests/test_doc_examples.py -v
+```
+
+Skip Ollama-dependent examples when Ollama is unavailable:
+```bash
+pytest tests/test_doc_examples.py -v -m "not requires_ollama"
+```
+
+## Formatting rules (fix any violations found)
+
+- Use **unindented** ` ```python ` fences (no leading spaces before the triple backtick)
+- Always include a language tag (` ```python ` or ` ```chatterlang `)
+- Standalone examples must include all imports and be runnable in isolation
+- Add `# skip-extract` as the first line of blocks that are intentionally non-runnable (fragments, setup code, external-service-only)
+
+## Scope
+
+$input

talkpipe-0.12.3/.github/prompts/tdd.prompt.md

@@ -0,0 +1,21 @@
+---
+mode: agent
+description: Follow TalkPipe TDD workflow. Use when implementing features, fixing bugs, or adding segments/sources. Enforces write-fail-fix-pass order.
+---
+
+Follow the TalkPipe TDD workflow for this change:
+
+1. **Write or update a test** in `tests/` that fails without the change. Prefer updating an existing test file over creating a new one.
+2. **Verify the test fails**: run `source .venv/bin/activate && pytest <test-file> -v`
+3. **Implement the change**
+4. **Verify the test passes**: re-run the same pytest command
+
+Constraints:
+- Tests mirror `src/` structure under `tests/talkpipe/`
+- Keep tests as short as possible while covering the functionality completely
+- Use `pytest.fixture` and `pytest-mock` for dependencies
+- Always use the `.venv` environment; abort and alert if it doesn't exist
+
+If a unit test is not reasonable (e.g., requires external LLM, is purely cosmetic), notify the user and explain why.
+
+The change to implement: $input

talkpipe-0.12.3/.github/prompts/update-entry-points.prompt.md

@@ -0,0 +1,26 @@
+---
+mode: agent
+description: Regenerate and apply talkpipe.sources and talkpipe.segments entry points from @register_source/@register_segment decorators. Use after adding new sources or segments, or when pyproject.toml entry points are out of sync.
+---
+
+Regenerate entry points from `@register_source` and `@register_segment` decorators and update `pyproject.toml`.
+
+Run from the project root:
+
+```bash
+source .venv/bin/activate
+python .cursor/skills/update-entry-points/scripts/update_entry_points.py
+```
+
+The script:
+1. Scans `src/talkpipe/` for `@register_source` and `@register_segment` decorators
+2. Generates updated entry-point TOML
+3. Replaces `[project.entry-points."talkpipe.sources"]` and `[project.entry-points."talkpipe.segments"]` in `pyproject.toml`
+4. Preserves all other `pyproject.toml` content
+
+**Dry run** (preview without writing):
+```bash
+python .cursor/skills/update-entry-points/scripts/update_entry_points.py --dry-run
+```
+
+After running, verify the expected entry appears in `pyproject.toml`.

{talkpipe-0.12.2 → talkpipe-0.12.3}/.github/workflows/ci-cd.yml

@@ -20,7 +20,7 @@ jobs:
         python-version: ['3.11', '3.12', '3.13']
     
     steps:
-    - uses: actions/checkout@v6
+    - uses: actions/checkout@v7
       with:
         fetch-depth: 0
     
@@ -30,7 +30,7 @@ jobs:
         python-version: ${{ matrix.python-version }}
     
     - name: Cache pip dependencies
-      uses: actions/cache@v5
+      uses: actions/cache@v6
       with:
         path: ~/.cache/pip
         key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
@@ -48,7 +48,7 @@ jobs:
     
     - name: Upload coverage to Codecov
       if: matrix.python-version == '3.11'
-      uses: codecov/codecov-action@v6
+      uses: codecov/codecov-action@v7
       with:
         files: ./coverage.xml
         flags: unittests
@@ -60,7 +60,7 @@ jobs:
       SAFETY_API_KEY: ${{ secrets.SAFETY_API_KEY }}
 
     steps:
-    - uses: actions/checkout@v6
+    - uses: actions/checkout@v7
       with:
         fetch-depth: 0
     
@@ -104,7 +104,7 @@ jobs:
     
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v6
+      uses: actions/checkout@v7
     
     - name: Log in to Container Registry
       uses: docker/login-action@v4
@@ -177,7 +177,7 @@ jobs:
     
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v6
+      uses: actions/checkout@v7
     
     - name: Initialize CodeQL
       uses: github/codeql-action/init@v4
@@ -196,7 +196,7 @@ jobs:
     if: github.event_name == 'release' && github.event.action == 'published'
     
     steps:
-    - uses: actions/checkout@v6
+    - uses: actions/checkout@v7
       with:
         fetch-depth: 0
     

{talkpipe-0.12.2 → talkpipe-0.12.3}/.vscode/settings.json

@@ -22,7 +22,6 @@
         "talkpipe"
     ],
     "python.testing.pytestArgs": [
-        "tests",
-        "--rootdir", "${workspaceFolder}"
+        "tests"
     ]
 }

{talkpipe-0.12.2 → talkpipe-0.12.3}/CHANGELOG.md

@@ -2,6 +2,88 @@
 
 ## Unreleased
 
+## 0.12.3
+
+- Fixed several doc-accuracy and rough-edge issues found during usability testing:
+  - `docs/architecture/configuration.md`'s example TOML named a dead `ollama_base_url` key;
+    it now shows the real `OLLAMA_SERVER_URL` key used by the README and code.
+  - `OllamaPromptAdapter` now catches connection failures and re-raises with the server URL
+    it tried and a pointer to `TALKPIPE_OLLAMA_SERVER_URL`, instead of a generic SDK error.
+  - `serverag` resolved `--embedding_*`/`--completion_*` defaults from the wrong config keys
+    (silently always falling through) and only validated provider config on the first query.
+    It now resolves the correct keys and builds the pipeline once at startup so a bad or
+    missing embedding/completion model or source fails immediately with an actionable error;
+    `quickstart.md`'s RAG example now includes the required completion flags.
+  - `extending-talkpipe.md`'s third-party plugin snippet registered a source under the
+    `talkpipe.segments` entry-point group instead of `talkpipe.sources`; fixed, and added a
+    complete end-to-end plugin example (package layout, `components.py`, `pyproject.toml`,
+    usage).
+  - `talkpipe_plugins --list` only reported the `talkpipe.plugins` entry-point group, so
+    components registered via `talkpipe.segments` / `talkpipe.sources` (the pattern most
+    third-party plugins use) were invisible even when working correctly. It now lists those
+    too.
+  - `makevectordatabase` now prints a completion summary (chunk count, output path, table,
+    embedding model/source) instead of exiting silently.
+  - `SearchResult.prompt_worthy_string` no longer surfaces internal underscore-prefixed
+    fields (e.g. the auto-generated `_doc_id`) to the LLM, so RAG answers over string-indexed
+    documents (no `title`/`source` field) don't cite a bare UUID.
+  - The misspelled segment aliases `addToLancDB` / `searchLancDB` remain functional for
+    backward compatibility but are now hidden from `available_names` (compiler error
+    suggestions) and `talkpipe_plugins --list` via a new `DEPRECATED_ALIASES` set in the
+    registry, so newcomers aren't shown two spellings with no indication which is canonical.
+  - Documented that `embedding_source="model2vec"` downloads the model from Hugging Face on
+    first use (cached after that); README tip and the model2vec guide now call this out.
+- Fixed a data-corruption bug in `makevectordatabase`'s document pipeline: `ProcessDocumentsSegment`
+  shingled chunks across file boundaries (no per-document grouping), so two small input files could
+  be merged into a single indexed row with the content of both but the source/title of only the last
+  one, and RAG citations would then point at the wrong file. `ShingleText` is now grouped by `source`
+  so shingles never cross a file boundary.
+- Fixed config key lookups being case-sensitive despite mixed casing conventions across the codebase
+  (`OLLAMA_SERVER_URL` vs. `default_model_name`, etc.): `TALKPIPE_*` environment variables now match
+  TOML config keys case-insensitively, so `TALKPIPE_default_model_name` and
+  `TALKPIPE_DEFAULT_MODEL_NAME` both work. Corrected config key names that had drifted from the
+  code in `configuration.md`, `model-and-source-configuration.md` (removed a fictional `DEFAULT_*`
+  key layer for `serverag`/`makevectordatabase` that doesn't exist), and
+  `makevectordatabase-and-serverag.md`.
+- Fixed a self-contradictory compiler error: a segment/source declared via a `talkpipe.segments` /
+  `talkpipe.sources` entry point that failed to import was reported as simply "not found," with a
+  "did you mean" suggestion pointing at the very name that just failed. `HybridRegistry` now
+  captures the underlying import error and the compiler reports it directly (e.g. "was declared by
+  a plugin but failed to load: `<error>`") instead of suggesting the broken name as its own fix.
+  Also invalidate import caches before entry-point discovery to reduce staleness right after an
+  editable install.
+- `chatterlang_script` now catches `CompileError` and prints just the error message instead of a
+  full Python traceback; pass `--verbose` to see the traceback for debugging.
+- Ollama "model not found" (404) responses are now wrapped with an actionable message suggesting
+  `ollama pull <model>`, matching the existing treatment of connection errors.
+- `talkpipe_plugins` with no arguments now defaults to `--list` instead of silently printing
+  nothing.
+- Missing `robots.txt` (404) now logs at debug/info instead of warning, since it's a normal,
+  expected condition, not an error.
+- `LlmBinaryAnswer.Answer` (used by `ragToBinaryAnswer` / `llmBinaryAnswer`) now has a friendly
+  `__str__` ("Yes: ..." / "No: ...") instead of printing as a raw Pydantic repr.
+- README: added a concrete example value for `TALKPIPE_OLLAMA_SERVER_URL`, and labeled Example 4's
+  sample scored output as illustrative/model-dependent (LLM scores vary by model and run).
+- Fixed `OllamaPromptAdapter.is_available()` checking the wrong server: it called the `ollama`
+  package's module-level `ollama.chat()`, which always targets a `Client` instance created once at
+  `import ollama` time (defaulting to `http://127.0.0.1:11434` unless `OLLAMA_HOST` happened to be
+  set at that moment) and never re-reads any env var afterward. This ignored TalkPipe's own
+  `server_url` / `OLLAMA_SERVER_URL` config entirely, so on machines running a local Ollama without
+  the configured model (but with a working remote Ollama server configured), `is_available()` — and
+  therefore the `requires_ollama` test fixture and any code checking availability — would report the
+  model unavailable even though it was reachable and correctly used everywhere else. It now routes
+  through the same `_chat_completion()` helper `execute()` uses, which builds an `ollama.Client`
+  pointed at the configured server.
+- Added a local `eliza` prompt-adapter source for `llmPrompt` and guided-generation
+  segments. The adapter is deterministic (no external API keys), uses the configured
+  model name as ELIZA's self-reference, supports multi-turn memory/fact callbacks,
+  and provides generic structured outputs for score/binary/term extraction schemas.
+  Added a matching ChatterLang example to model/source configuration docs.
+- Fixed single-turn (`multi_turn=False`) prompt-adapter state handling so `_summary_message`
+  is cleared after each response and does not leak conversation memory between calls.
+- Fixed a CI import failure in `talkpipe.chatterlang.registry` by importing `List`
+  for the `available_names` return annotation, preventing `NameError` during module import.
+
 ## v0.12.2
 - Added batch embedding support: embedding adapters expose `execute_one` and `execute_batch`;
   `execute` remains as a deprecated alias for `execute_one` (removed in 1.0). `llmEmbed` extends

{talkpipe-0.12.2/src/talkpipe.egg-info → talkpipe-0.12.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: talkpipe
-Version: 0.12.2
+Version: 0.12.3
 Summary: Python internal and external DSL for writing generative AI analytics
 Author-email: Travis Bauer <tlbauer@sandia.gov>
 Maintainer-email: Travis Bauer <tlbauer@sandia.gov>
@@ -36,6 +36,7 @@ Requires-Dist: pyyaml
 Requires-Dist: greenlet
 Requires-Dist: networkx
 Requires-Dist: starlette>=0.49.1
+Requires-Dist: build>=1.5.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-mock; extra == "dev"
@@ -79,7 +80,7 @@ This README is a high-level overview. Use the **[documentation map](#documentati
 
 ## What Can You Do With TalkPipe?
 
-- **Chat with LLMs** - Create multi-turn conversations with OpenAI, Ollama, or Anthropic models in just 2 lines of code
+- **Chat with LLMs** - Create multi-turn conversations with OpenAI, Ollama, or Anthropic models in just a few lines of code
 - **Process Documents** - Extract text from PDFs, analyze research papers, score content relevance
 - **Build RAG Pipelines** - Create end-to-end Retrieval-Augmented Generation workflows with vector databases
 - **Analyze Web Content** - Download web pages (respecting robots.txt), extract readable text, and summarize
@@ -128,7 +129,7 @@ These applications are entry points for different usage scenarios, from interact
 
 ## Quick Start
 
-**Requirements:** Python 3.11 or newer.
+**Requirements:** Python 3.11 or newer. Check your version first with `python3 --version` — it must report 3.11 or higher before installing.
 
 ```bash
 pip install talkpipe
@@ -144,14 +145,34 @@ pip install talkpipe[model2vec] # In-process static embeddings (also in [all])
 # Or: pip install talkpipe[all]
 ```
 
-Configure API keys and provider URLs via environment variables (for example `TALKPIPE_openai_api_key`) or `~/.talkpipe.toml`. If TalkPipe runs on a different machine than your Ollama server, set `TALKPIPE_OLLAMA_SERVER_URL` to that host. See **[Configuration](docs/architecture/configuration.md)** for details and ChatterLang `$var` substitution.
+Configure API keys and provider URLs via environment variables (for example `OPENAI_API_KEY` and `ANTHROPIC_API_KEY`) or `~/.talkpipe.toml`. If TalkPipe runs on a different machine than your Ollama server, set `TALKPIPE_OLLAMA_SERVER_URL` to that host, e.g. `export TALKPIPE_OLLAMA_SERVER_URL="http://192.168.1.50:11434"` (a bare host/IP with no scheme or port, like `"192.168.1.50"`, also works). See **[Configuration](docs/architecture/configuration.md)** for details and ChatterLang `$var` substitution.
 
-Multi-turn chat in a few lines:
+Hello world (no LLM server required):
+
+> **Note:** `source="eliza"` is **not** an LLM provider. It is a local, deterministic adapter for experimenting with TalkPipe/ChatterLang syntax and multi-turn flow when you do not yet have Ollama/OpenAI/Anthropic access.
+
+```python
+from talkpipe.chatterlang import compiler
+
+script = '| print | llmPrompt[model="Dr. Eliza", source="eliza", multi_turn=True] | print'
+chat = compiler.compile(script).as_function(single_in=True, single_out=True)
+
+chat("Hello, my name is Alice.")
+chat("What's my name?")
+```
+
+> **Tip:** `from talkpipe.chatterlang import compile` is equivalent to the `compiler.compile(...)` style above — both styles work throughout the docs.
+
+Multi-turn chat (requires a local model server):
+
+> **Prerequisite:** this example uses Ollama, a separate application (not just the `talkpipe[ollama]` Python package). Install and start it from https://ollama.com/download, then pull the model with `ollama pull llama3.2`. Cloud users can skip Ollama and substitute `source="openai"` or `source="anthropic"` (see the commented variants below).
 
 ```python
 from talkpipe.chatterlang import compiler
 
 script = '| print | llmPrompt[model="llama3.2", source="ollama", multi_turn=True] | print'
+# Using OpenAI:    model="gpt-4o-mini", source="openai"      (set OPENAI_API_KEY)
+# Using Anthropic: model="claude-haiku-4-5", source="anthropic" (set ANTHROPIC_API_KEY)
 chat = compiler.compile(script).as_function(single_in=True, single_out=True)
 
 response = chat("Hello! My name is Alice.")
@@ -177,6 +198,8 @@ rag = compiler.compile(
 rag("What is TalkPipe?")
 ```
 
+> **No Ollama server?** Swap `embedding_source="model2vec"` and `embedding_model="minishlab/potion-base-8M"` for offline embeddings (included in `talkpipe[all]`). The first run downloads the model from Hugging Face (a few files, ~30 MB); after that it's cached and needs no network — see [Precache for offline use](docs/guides/model2vec-embeddings.md#precache-for-offline-use) to pre-download for air-gapped environments. Note: the `ragToText` completion step still requires an LLM provider. See the [model2vec guide](docs/guides/model2vec-embeddings.md).
+
 # Core Components
 
 ## 1. The Pipe API (Internal DSL)
@@ -410,7 +433,9 @@ CONST iot_prompt = "Rate 0-10 how relevant this is to IoT researchers. Consider
 evaluator = compiler.compile(script).as_function(single_in=False, single_out=False)
 results = evaluator(articles)
 
-# Output shows only relevant articles with their scores:
+# Output shows only relevant articles with their scores. Scores are assigned by the
+# LLM, so they (and which rows survive the >6 filter) vary by model and run; with
+# some models only one or two of the four articles may pass. Illustrative example:
 # {'title': 'New LLM Model Released', 'ai_score': 9, 'iot_score': 2, 'max_score': 9}
 # {'title': 'Smart Home IoT Devices', 'ai_score': 3, 'iot_score': 9, 'max_score': 9}
 # {'title': 'RAG Systems in Production', 'ai_score': 8, 'iot_score': 2, 'max_score': 8}
@@ -581,7 +606,7 @@ smtp_port = 587
 Environment variables use the `TALKPIPE_` prefix:
 ```bash
 export TALKPIPE_email_password="your-password"
-export TALKPIPE_openai_api_key="sk-..."
+export OPENAI_API_KEY="sk-..."
 ```
 
 ### Performance Optimization
@@ -638,17 +663,17 @@ def multiplyBy(items, factor=2):
     for item in items:
         yield item * factor
 
-# Use it to double the Fibonacci numbers
+# Use it to multiply each value in the range by 3
 pipeline = arange(lower=5, upper=10) | multiplyBy(factor=3) | io.Print()
 result = pipeline.as_function(single_out=False)()
 
 # Output:
-# 0
-# 3
-# 3
-# 6
-# 9
-# Returns: [0, 3, 3, 6, 9]
+# 15
+# 18
+# 21
+# 24
+# 27
+# Returns: [15, 18, 21, 24, 27]
 ```
 
 **Field Segments** provide a convenient way to create 1:1 segments:

{talkpipe-0.12.2 → talkpipe-0.12.3}/README.md

@@ -20,7 +20,7 @@ This README is a high-level overview. Use the **[documentation map](#documentati
 
 ## What Can You Do With TalkPipe?
 
-- **Chat with LLMs** - Create multi-turn conversations with OpenAI, Ollama, or Anthropic models in just 2 lines of code
+- **Chat with LLMs** - Create multi-turn conversations with OpenAI, Ollama, or Anthropic models in just a few lines of code
 - **Process Documents** - Extract text from PDFs, analyze research papers, score content relevance
 - **Build RAG Pipelines** - Create end-to-end Retrieval-Augmented Generation workflows with vector databases
 - **Analyze Web Content** - Download web pages (respecting robots.txt), extract readable text, and summarize
@@ -69,7 +69,7 @@ These applications are entry points for different usage scenarios, from interact
 
 ## Quick Start
 
-**Requirements:** Python 3.11 or newer.
+**Requirements:** Python 3.11 or newer. Check your version first with `python3 --version` — it must report 3.11 or higher before installing.
 
 ```bash
 pip install talkpipe
@@ -85,14 +85,34 @@ pip install talkpipe[model2vec] # In-process static embeddings (also in [all])
 # Or: pip install talkpipe[all]
 ```
 
-Configure API keys and provider URLs via environment variables (for example `TALKPIPE_openai_api_key`) or `~/.talkpipe.toml`. If TalkPipe runs on a different machine than your Ollama server, set `TALKPIPE_OLLAMA_SERVER_URL` to that host. See **[Configuration](docs/architecture/configuration.md)** for details and ChatterLang `$var` substitution.
+Configure API keys and provider URLs via environment variables (for example `OPENAI_API_KEY` and `ANTHROPIC_API_KEY`) or `~/.talkpipe.toml`. If TalkPipe runs on a different machine than your Ollama server, set `TALKPIPE_OLLAMA_SERVER_URL` to that host, e.g. `export TALKPIPE_OLLAMA_SERVER_URL="http://192.168.1.50:11434"` (a bare host/IP with no scheme or port, like `"192.168.1.50"`, also works). See **[Configuration](docs/architecture/configuration.md)** for details and ChatterLang `$var` substitution.
 
-Multi-turn chat in a few lines:
+Hello world (no LLM server required):
+
+> **Note:** `source="eliza"` is **not** an LLM provider. It is a local, deterministic adapter for experimenting with TalkPipe/ChatterLang syntax and multi-turn flow when you do not yet have Ollama/OpenAI/Anthropic access.
+
+```python
+from talkpipe.chatterlang import compiler
+
+script = '| print | llmPrompt[model="Dr. Eliza", source="eliza", multi_turn=True] | print'
+chat = compiler.compile(script).as_function(single_in=True, single_out=True)
+
+chat("Hello, my name is Alice.")
+chat("What's my name?")
+```
+
+> **Tip:** `from talkpipe.chatterlang import compile` is equivalent to the `compiler.compile(...)` style above — both styles work throughout the docs.
+
+Multi-turn chat (requires a local model server):
+
+> **Prerequisite:** this example uses Ollama, a separate application (not just the `talkpipe[ollama]` Python package). Install and start it from https://ollama.com/download, then pull the model with `ollama pull llama3.2`. Cloud users can skip Ollama and substitute `source="openai"` or `source="anthropic"` (see the commented variants below).
 
 ```python
 from talkpipe.chatterlang import compiler
 
 script = '| print | llmPrompt[model="llama3.2", source="ollama", multi_turn=True] | print'
+# Using OpenAI:    model="gpt-4o-mini", source="openai"      (set OPENAI_API_KEY)
+# Using Anthropic: model="claude-haiku-4-5", source="anthropic" (set ANTHROPIC_API_KEY)
 chat = compiler.compile(script).as_function(single_in=True, single_out=True)
 
 response = chat("Hello! My name is Alice.")
@@ -118,6 +138,8 @@ rag = compiler.compile(
 rag("What is TalkPipe?")
 ```
 
+> **No Ollama server?** Swap `embedding_source="model2vec"` and `embedding_model="minishlab/potion-base-8M"` for offline embeddings (included in `talkpipe[all]`). The first run downloads the model from Hugging Face (a few files, ~30 MB); after that it's cached and needs no network — see [Precache for offline use](docs/guides/model2vec-embeddings.md#precache-for-offline-use) to pre-download for air-gapped environments. Note: the `ragToText` completion step still requires an LLM provider. See the [model2vec guide](docs/guides/model2vec-embeddings.md).
+
 # Core Components
 
 ## 1. The Pipe API (Internal DSL)
@@ -351,7 +373,9 @@ CONST iot_prompt = "Rate 0-10 how relevant this is to IoT researchers. Consider
 evaluator = compiler.compile(script).as_function(single_in=False, single_out=False)
 results = evaluator(articles)
 
-# Output shows only relevant articles with their scores:
+# Output shows only relevant articles with their scores. Scores are assigned by the
+# LLM, so they (and which rows survive the >6 filter) vary by model and run; with
+# some models only one or two of the four articles may pass. Illustrative example:
 # {'title': 'New LLM Model Released', 'ai_score': 9, 'iot_score': 2, 'max_score': 9}
 # {'title': 'Smart Home IoT Devices', 'ai_score': 3, 'iot_score': 9, 'max_score': 9}
 # {'title': 'RAG Systems in Production', 'ai_score': 8, 'iot_score': 2, 'max_score': 8}
@@ -522,7 +546,7 @@ smtp_port = 587
 Environment variables use the `TALKPIPE_` prefix:
 ```bash
 export TALKPIPE_email_password="your-password"
-export TALKPIPE_openai_api_key="sk-..."
+export OPENAI_API_KEY="sk-..."
 ```
 
 ### Performance Optimization
@@ -579,17 +603,17 @@ def multiplyBy(items, factor=2):
     for item in items:
         yield item * factor
 
-# Use it to double the Fibonacci numbers
+# Use it to multiply each value in the range by 3
 pipeline = arange(lower=5, upper=10) | multiplyBy(factor=3) | io.Print()
 result = pipeline.as_function(single_out=False)()
 
 # Output:
-# 0
-# 3
-# 3
-# 6
-# 9
-# Returns: [0, 3, 3, 6, 9]
+# 15
+# 18
+# 21
+# 24
+# 27
+# Returns: [15, 18, 21, 24, 27]
 ```
 
 **Field Segments** provide a convenient way to create 1:1 segments:

{talkpipe-0.12.2 → talkpipe-0.12.3}/docs/api-reference/talkpipe-plugin-manager.md

@@ -33,8 +33,18 @@ Loaded plugins (2):
 
 Failed plugins (1):
   ✗ broken-plugin
+
+Segments registered via 'talkpipe.segments' entry points (98):
+  addToLanceDB -> talkpipe.search.lancedb:add_to_lancedb
+  ...
+
+Sources registered via 'talkpipe.sources' entry points (9):
+  greetings -> mytp.components:greetings
+  ...
 ```
 
+"Loaded plugins" only covers the whole-module `talkpipe.plugins` entry point group (see [Plugin Discovery](#plugin-discovery) below). If you registered components directly via the `talkpipe.segments` / `talkpipe.sources` entry point groups instead (the pattern most third-party plugins use — see [Extending TalkPipe](../architecture/extending-talkpipe.md#entry-points-for-distributable-components)), they show up here rather than under "Loaded plugins". This is the way to confirm your installed component is discoverable without having to run a pipeline that uses it.
+
 ### Reload a Plugin
 
 Reload a specific plugin by name (useful during development):