nodetool-core 0.7.0__tar.gz

nodetool_core-0.7.0/.cursorignore

@@ -0,0 +1,4 @@
+build/
+dist/
+node_modules/
+**/node_modules/

nodetool_core-0.7.0/.dockerignore

@@ -0,0 +1,9 @@
+Dockerfile
+electron/node_modules/
+web/node_modules/
+.venv/
+*.pyc
+*.pyo
+*.pyd
+__pycache__
+.pytest_cache

nodetool_core-0.7.0/.env.example

@@ -0,0 +1,134 @@
+# Example Environment Configuration
+# Copy this file to .env.development, .env.test, or .env.production and fill in your values
+# You can also copy to .env for quick local development
+
+# Basic Configuration
+PYTHONPATH=src
+ENV=development
+
+# API Keys (replace with your actual keys)
+ANTHROPIC_API_KEY=your_anthropic_api_key_here
+MINIMAX_API_KEY=your_minimax_api_key_here
+OPENAI_API_KEY=your_openai_api_key_here
+OPENROUTER_API_KEY=your_openrouter_api_key_here
+TOGETHER_API_KEY=your_together_api_key_here
+GEMINI_API_KEY=your_gemini_api_key_here
+HF_TOKEN=your_huggingface_token_here
+REPLICATE_API_TOKEN=your_replicate_token_here
+ELEVENLABS_API_KEY=your_elevenlabs_api_key_here
+FAL_API_KEY=your_fal_api_key_here
+SERPAPI_API_KEY=your_serpapi_key_here
+APIFY_API_KEY=your_apify_api_key_here
+KIE_API_KEY=your_kie_api_key_here
+AIME_API_KEY=your_aime_api_key
+
+# RunPod (for cloud deployment)
+RUNPOD_API_KEY=your_runpod_api_key_here
+
+# Google Services
+GOOGLE_MAIL_USER=your_gmail_address
+GOOGLE_APP_PASSWORD=your_google_app_password
+
+# DataForSEO
+DATA_FOR_SEO_LOGIN=your_dataforseo_login
+DATA_FOR_SEO_PASSWORD=your_dataforseo_password
+
+# SERP Provider Selection
+# Choose which SERP provider to use: serpapi, apify, or dataforseo
+# If not set, auto-selects based on available API keys (SerpApi > Apify > DataForSEO)
+# SERP_PROVIDER=serpapi
+
+# Browser automation
+BROWSER_URL=your_browser_instance_url
+
+# Database Configuration
+# For development: use SQLite (now stored in data directory for persistence across updates)
+# Windows: %LOCALAPPDATA%/nodetool/nodetool.sqlite3
+# Linux/macOS: ~/.local/share/nodetool/nodetool.sqlite3
+DB_PATH=~/.local/share/nodetool/nodetool.sqlite3
+
+# For production: use PostgreSQL
+# POSTGRES_DB=nodetool
+# POSTGRES_USER=nodetool_user
+# POSTGRES_PASSWORD=your_postgres_password
+# POSTGRES_HOST=localhost
+# POSTGRES_PORT=5432
+
+# Or use Supabase
+# SUPABASE_URL=https://your-project.supabase.co
+# SUPABASE_KEY=your_supabase_service_role_key        # Service role key for project API access
+# SUPABASE_POSTGRES_URL=postgresql://postgres...     # PostgreSQL connection URL for migrations (from Supabase Dashboard > Settings > Database > Connection String)
+# NODE_SUPABASE_URL=https://user-nodes.supabase.co    # Optional: user-provided Supabase for nodes
+# NODE_SUPABASE_KEY=your_user_node_service_key        # Kept separate from core SUPABASE_KEY
+# NODE_SUPABASE_SCHEMA=public
+# NODE_SUPABASE_TABLE_PREFIX=node_
+
+# Storage Configuration
+ASSET_BUCKET=images
+ASSET_TEMP_BUCKET=temp-images
+
+# S3 Configuration (for production)
+# S3_ACCESS_KEY_ID=your_s3_access_key
+# S3_SECRET_ACCESS_KEY=your_s3_secret_key
+# S3_ENDPOINT_URL=https://s3.amazonaws.com
+# S3_REGION=us-east-1
+
+# Asset domains (for production)
+# ASSET_DOMAIN=https://your-cdn-domain.com
+# ASSET_TEMP_DOMAIN=https://your-temp-cdn-domain.com
+
+# Vector Database
+CHROMA_PATH=~/.local/share/nodetool/chroma
+# CHROMA_URL=http://localhost:7777  # For remote ChromaDB
+# CHROMA_TOKEN=your_chroma_token
+
+# External Services
+OLLAMA_API_URL=http://127.0.0.1:11434
+LMSTUDIO_API_URL=http://127.0.0.1:1234
+NODETOOL_API_URL=http://localhost:7777
+
+# Llama.cpp Server
+# Set this to enable the LlamaCpp provider for local GGUF models
+# Example: LLAMA_CPP_URL=http://127.0.0.1:8080
+# LLAMA_CPP_URL=
+# LLAMA_CPP_CONTEXT_LENGTH=128000  # Optional: context window size in tokens
+
+# Folders
+# FONT_PATH=/path/to/fonts
+# COMFY_FOLDER=/path/to/ComfyUI
+
+# Caching
+# MEMCACHE_HOST=localhost
+# MEMCACHE_PORT=11211
+
+# Logging and Monitoring
+LOG_LEVEL=INFO
+DEBUG=false
+# SENTRY_DSN=your_sentry_dsn_for_error_tracking
+# TRACELOOP_ENABLED=true
+# TRACELOOP_API_KEY=your_traceloop_api_key
+# TRACELOOP_BASE_URL=https://api.traceloop.com
+# TRACELOOP_DISABLE_BATCH=true
+# TRACELOOP_APP_NAME=nodetool
+
+# OpenTelemetry Auto-Instrumentation (for server environments)
+# Run with: opentelemetry-instrument uvicorn nodetool.api.app:app --host 0.0.0.0 --port 8000
+# Or use the provided script: ./scripts/server-otel.sh
+OTEL_SERVICE_NAME=nodetool-api                              # Service name for traces
+OTEL_TRACES_EXPORTER=console,otlp                            # Exporters: console,otlp (comma-separated)
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317           # OTLP collector endpoint (gRPC)
+OTEL_EXPORTER_OTLP_PROTOCOL=grpc                             # Protocol: grpc, http/protobuf, http/json
+OTEL_METRICS_EXPORTER=otlp                                   # Metrics exporter: console,otlp,none
+OTEL_LOGS_EXPORTER=none                                      # Logs exporter: console,otlp,none
+OTEL_SAMPLING_RATIO=1.0                                      # Sampling ratio 0.0-1.0
+OTEL_RESOURCE_ATTRIBUTES=deployment.environment=development  # Resource attributes
+
+# Authentication
+# Select provider: none | local | static | supabase
+AUTH_PROVIDER=local
+
+# OAuth Configuration
+# GitHub OAuth App credentials (for OAuth PKCE flow)
+# Get these from https://github.com/settings/developers
+GITHUB_CLIENT_ID=your_github_client_id_here
+GITHUB_CLIENT_SECRET=your_github_client_secret_here

nodetool_core-0.7.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,2 @@
+[← Back to Docs Index](../../docs/index.md)
+

nodetool_core-0.7.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"

nodetool_core-0.7.0/.github/opencode-memory/README.md

@@ -0,0 +1,103 @@
+# OpenCode Long-Term Memory
+
+This directory contains persistent knowledge for OpenCode workflows in **nodetool-core**. Content is organized into folders by topic, with individual files per issue/insight to keep context focused and reduce merge conflicts.
+
+## Directory Structure
+
+```
+opencode-memory/
+├── README.md              # This file - overview and usage
+├── features.md            # List of user-facing features
+├── build-test-lint.md     # Quality requirements and commands
+├── tech-stack.md          # Key technologies and versions
+├── repository-context.md  # Project structure and conventions
+│
+├── issues/                # Known issues organized by topic
+│   ├── README.md          # How to add new issues
+│   ├── testing/
+│   ├── linting/
+│   ├── typing/
+│   ├── workflows/
+│   ├── api/
+│   ├── storage/
+│   ├── dependencies/
+│   ├── config/
+│   └── ci/
+│
+└── insights/              # Best practices organized by topic
+    ├── README.md          # How to add new insights
+    ├── architecture/
+    ├── performance/
+    ├── testing/
+    ├── code-quality/
+    ├── async/
+    ├── workflows/
+    ├── api/
+    ├── storage/
+    └── deployment/
+```
+
+## How to Use
+
+### Before Making Changes
+
+1. Check `features.md` to avoid duplicate feature work
+2. List `issues/` to discover relevant topics, then read descriptive files
+3. List `insights/` to discover best practices, then read descriptive files
+4. Read `repository-context.md`
+
+### After Completing Work
+
+1. New feature? → Add ONE line to `features.md`
+2. Solved a tricky issue? → Create a file in `issues/<topic>/`
+3. Discovered a best practice? → Create a file in `insights/<topic>/`
+
+## File Naming Convention
+
+Use descriptive, kebab-case names that make the topic obvious at a glance:
+- `issues/testing/pytest-async-timeouts.md`
+- `issues/workflows/workflow-runner-state-leaks.md`
+- `insights/async/non-blocking-db-queries.md`
+
+## File Format
+
+### Issue Files (`issues/<topic>/*.md`)
+
+```markdown
+# Issue Title
+
+**Problem**: One sentence describing the issue
+
+**Solution**: One sentence or brief code snippet
+
+**Why**: Brief explanation (optional)
+
+**Files**: Related files (optional)
+
+**Date**: YYYY-MM-DD
+```
+
+### Insight Files (`insights/<topic>/*.md`)
+
+```markdown
+# Insight Title
+
+**Insight**: What was learned or discovered
+
+**Rationale**: Why it matters
+
+**Example**: Code example (if applicable)
+
+**Impact**: Measurable benefit (if known)
+
+**Files**: Related files (optional)
+
+**Date**: YYYY-MM-DD
+```
+
+## Benefits
+
+✅ Fewer merge conflicts with file-based entries
+✅ Focused context per issue or insight
+✅ Easier discovery by listing topic folders
+✅ Cleaner diffs for updates and removals

nodetool_core-0.7.0/.github/opencode-memory/USAGE-GUIDE.md

@@ -0,0 +1,153 @@
+# Memory System Usage Guide for AI Agents
+
+This guide explains how AI agents working on nodetool-core should use the OpenCode memory system.
+
+## Quick Start
+
+### Before Every Task
+
+1. **Read repository-context.md** (Required)
+   - Contains essential project information
+   - Explains structure, conventions, and commands
+   - Provides environment setup details
+
+2. **Check issues/ folder** (If encountering issues)
+    - See if your problem has been solved before
+    - Avoid redundant debugging
+    - Learn from past solutions
+
+3. **Review insights.md** (For architectural work)
+   - Understand key design patterns
+   - Learn important architectural decisions
+   - Follow established conventions
+
+## When to Update Memory Files
+
+### Update repository-context.md When:
+- Adding new major project conventions
+- Changing build/test/lint commands
+- Updating development environment setup
+- Adding new core dependencies or system requirements
+- Documenting new architectural components
+
+### Add files to issues/ When:
+- You solve a non-trivial problem that took >10 minutes
+- You encounter a confusing error with a clear solution
+- You fix an issue that's likely to recur
+- You discover an environment-specific quirk
+- You find a workaround for a known limitation
+
+### Update insights.md When:
+- You discover an important architectural pattern
+- You learn why something is designed a certain way
+- You identify a performance consideration
+- You find a security best practice specific to this codebase
+- You document a design decision that should be followed
+
+## What NOT to Document
+
+Avoid documenting:
+- Temporary workarounds that should be fixed properly
+- Personal preferences without justification
+- Information already in official docs (README, CONTRIBUTING)
+- Overly specific details that change frequently
+- One-off issues unlikely to recur
+- Secrets or sensitive information
+
+## Examples of Good Memory Entries
+
+### Good Common Issue Entry
+```markdown
+### Import Errors After Adding Dependencies
+**Date Discovered**: 2024-01-10
+**Context**: New dependencies not found after adding to pyproject.toml
+**Solution**: Run `uv sync --all-extras --dev` or `pip install -e .`
+**Related Files**: `pyproject.toml`
+**Prevention**: Document dependency installation in PR description
+```
+
+### Good Insight Entry
+```markdown
+### Async-First Design
+**Date**: 2024-01-10
+**Category**: Architecture
+**Insight**: The codebase is heavily async-oriented. Most subsystems use asyncio.
+**Impact**: New code should prefer async/await patterns. Avoid blocking calls.
+**Examples**: `src/nodetool/workflows/`, `src/nodetool/agents/`
+```
+
+### Bad Entry (Too Specific)
+```markdown
+### Fixed typo on line 42 of utils.py
+**Date**: 2024-01-10
+**Solution**: Changed "teh" to "the"
+```
+This is too specific and not worth documenting.
+
+### Bad Entry (Temporary Workaround)
+```markdown
+### Temporarily disable failing test
+**Solution**: Comment out test_complicated_function() until we fix it
+```
+This is a workaround, not a proper solution.
+
+## Memory File Maintenance
+
+### Monthly Review (Suggested)
+- Remove outdated information
+- Consolidate duplicate entries
+- Update dates and examples
+- Archive old entries that are no longer relevant
+- Verify all file paths and examples still exist
+
+### Keep It Lean
+- Each file should be readable in 2-3 minutes
+- Focus on actionable information
+- Use clear, concise language
+- Link to detailed docs when appropriate
+
+## Integration with Workflows
+
+### opencode-hourly-test.yaml
+- Reads memory before running tests
+- Adds files to issues/ if fixing recurring problems
+- Records test-specific patterns in insights/
+
+### opencode-hourly-improve.yaml
+- Consults memory before scanning for issues
+- Documents discovered patterns in insights/
+- Adds files to issues/
+
+### opencode.yml (Comment-triggered)
+- System prompt directs agent to memory files
+- Agent should read relevant memory before starting
+- Updates memory after completing significant work
+
+## Benefits of Proper Memory Usage
+
+✅ **Faster problem solving** - Check if issue is already solved
+✅ **Consistent code quality** - Follow documented patterns
+✅ **Institutional knowledge** - Build understanding over time
+✅ **Reduced redundancy** - Don't solve the same problem twice
+✅ **Better onboarding** - New agents learn from past work
+✅ **Pattern recognition** - Identify recurring issues
+
+## Measuring Success
+
+Good memory usage leads to:
+- Fewer repeated issues in PRs
+- More consistent code patterns
+- Faster resolution times
+- Better PR descriptions (referencing past solutions)
+- Proactive prevention of known issues
+
+## Questions?
+
+If the memory system isn't working well:
+1. Are entries too vague or too specific?
+2. Is information duplicated across files?
+3. Are entries kept up-to-date?
+4. Are agents actually reading the files?
+5. Is the format easy to scan quickly?
+
+Adjust the system based on what actually helps with coding work.

nodetool_core-0.7.0/.github/opencode-memory/build-test-lint.md

@@ -0,0 +1,14 @@
+# Build, Test, Lint
+
+## Required Commands
+
+```bash
+make typecheck
+make lint
+make test
+```
+
+## Notes
+
+- Use Python 3.11+ with dependencies installed via `uv sync --all-extras --dev`.
+- Keep async code non-blocking; prefer `async`/`await` patterns.

nodetool_core-0.7.0/.github/opencode-memory/features.md

@@ -0,0 +1,24 @@
+# Feature Inventory
+
+- **Workflow Engine**: Executes async workflows in Python
+- **Node System**: Typed nodes with media refs and processing context
+- **Agent Framework**: LLM-backed planning and tool execution
+- **API Server**: FastAPI HTTP/WebSocket services
+- **Storage Layer**: Pluggable persistence backends
+- **Async Utilities**: `AsyncSemaphore` and `gather_with_concurrency` for async concurrency control
+- **Async Iterators**: `AsyncByteStream` for async byte sequence iteration in chunks, plus `async_take`, `async_slice`, `async_first`, `async_list`, `async_map`, `async_merge`, `async_filter`, `async_flat_map`, `async_reduce`, `async_partition`, and `async_chunked` utilities for async iterable manipulation
+- **Retry Utilities**: `retry_with_exponential_backoff` and `RetryPolicy` for handling transient failures
+- **Timeout Utilities**: `timeout`, `with_timeout`, `TimeoutPolicy`, and `TimeoutContext` for async timeout control
+- **Batching Utilities**: `batched_async_iterable` and `process_in_batches` for async batch processing
+- **Rate Limiting**: `AsyncTokenBucket` and `AsyncRateLimiter` for controlling operation rates (token bucket algorithm)
+- **Circuit Breaker**: `CircuitBreaker`, `MultiCircuitBreaker`, and `CircuitBreakerConfig` for preventing cascading failures in distributed systems
+- **Async Lock**: `AsyncLock` for exclusive resource access with timeout support, complementing `AsyncSemaphore`
+- **Task Group Management**: `AsyncTaskGroup` for managing groups of related async tasks with spawn, run, cancel, and result collection
+- **Priority Queue**: `AsyncPriorityQueue` for priority-based async task scheduling with configurable max size and timeout support
+- **Async Event**: `AsyncEvent` for inter-task signaling with one-shot and auto-reset modes, supports value passing and predicate-based waiting
+- **Async Barrier**: `AsyncBarrier` for synchronizing multiple coroutines at a synchronization point, useful for phased concurrent operations
+- **Async Condition**: `AsyncCondition` for condition variables allowing tasks to wait until notified by another task, with lock-based coordination to prevent race conditions
+- **Async Reader-Writer Lock**: `AsyncReaderWriterLock` for multiple concurrent readers with exclusive writer access, using writer-preference semantics to prevent starvation
+- **Async Channel**: `AsyncChannel` for producer-consumer patterns with send/receive/close operations, async iteration, and fan-in/fan-out utilities for channel composition
+- **Debounce & Throttle**: `AsyncDebounce`, `AsyncThrottle`, and `AdaptiveThrottle` for controlling async function execution frequency, useful for rate limiting and preventing excessive API calls
+- **Resource Pool**: `AsyncResourcePool` for managing reusable async resources like HTTP clients, database connections, or other expensive-to-create objects with lazy creation, size limits, expiration, and graceful shutdown

nodetool_core-0.7.0/.github/opencode-memory/insights/README.md

@@ -0,0 +1,3 @@
+# Insights Index
+
+Create one insight file per topic. Use descriptive, kebab-case filenames and keep entries focused.

nodetool_core-0.7.0/.github/opencode-memory/insights/accessibility/logging-with-context.md

@@ -0,0 +1,32 @@
+# Logging with Context
+
+**Insight**: Error logs should include sufficient context for debugging (user IDs, request details, timestamps) to enable effective troubleshooting.
+
+**Rationale**: Logs without context make it difficult to trace issues back to specific requests or users. Adding structured context improves observability and debugging.
+
+**Best Practices**:
+1. **Include user context**: Add user IDs, workflow IDs, or other identifiers
+2. **Request context**: Include method, path, and client information
+3. **Use structured logging**: Use proper log levels and format parameters
+4. **Avoid string concatenation**: Use %s formatting or f-strings for lazy evaluation
+
+**Example Pattern**:
+```python
+# Before:
+log.error(f"Request validation error: {exc}")
+
+# After:
+log.error(
+    "Request validation error: %s | Method: %s | Path: %s | Client: %s",
+    exc.errors(),
+    request.method,
+    request.url.path,
+    request.client.host if request.client else "unknown",
+)
+```
+
+**Impact**: Better traceability of issues, easier debugging, improved incident response.
+
+**Files**: `src/nodetool/api/server.py`, `src/nodetool/api/workspace.py`
+
+**Date**: 2026-02-24

nodetool_core-0.7.0/.github/opencode-memory/insights/accessibility/user-friendly-error-messages.md

@@ -0,0 +1,32 @@
+# User-Friendly Error Messages
+
+**Insight**: Error messages should be actionable and user-facing, while detailed technical information should be logged server-side for debugging.
+
+**Rationale**: Raw exception strings expose internal implementation details and are not helpful to end users. Users need clear, actionable error messages that explain what went wrong and what they can do about it.
+
+**Best Practices**:
+1. **User-facing messages**: Explain what went wrong and suggest next steps
+2. **Server-side logs**: Include full context (user IDs, request details, full stack traces)
+3. **Consistent format**: Use similar structure across all error responses
+4. **Appropriate detail**: More detail in development, sanitized in production
+
+**Example Pattern**:
+```python
+try:
+    # operation
+except SpecificException as e:
+    log.error("Context about what failed: %s", e, extra={"user_id": user, "request_id": id})
+    raise HTTPException(
+        status_code=appropriate_code,
+        detail="User-friendly message explaining what to do",
+    ) from e
+```
+
+**Impact**: Improved user experience, better debugging capability, enhanced security by not exposing internals.
+
+**Files**:
+- `src/nodetool/api/server.py` - Validation error handling
+- `src/nodetool/api/workspace.py` - Consistent error messages
+- `src/nodetool/cli.py` - Enhanced CLI error messages
+
+**Date**: 2026-02-24

nodetool_core-0.7.0/.github/opencode-memory/insights/api/README.md

@@ -0,0 +1,3 @@
+# API Insights
+
+Capture FastAPI, WebSocket, and request validation patterns.

nodetool_core-0.7.0/.github/opencode-memory/insights/architecture/README.md

@@ -0,0 +1,3 @@
+# Architecture Insights
+
+Document architectural decisions and patterns.

nodetool_core-0.7.0/.github/opencode-memory/insights/async/README.md

@@ -0,0 +1,3 @@
+# Async Insights
+
+Capture async/await patterns, concurrency tips, and blocking call avoidance.

nodetool_core-0.7.0/.github/opencode-memory/insights/async/async-concurrency-utilities.md

@@ -0,0 +1,41 @@
+# Async Concurrency Utilities
+
+**Insight**: Added `AsyncSemaphore` and `gather_with_concurrency` utilities in `src/nodetool/concurrency/async_utils.py` for managing async concurrency control.
+
+**Rationale**: The codebase heavily uses async patterns, and these utilities provide common patterns for:
+- Rate limiting concurrent operations with timeout support
+- Batched execution of async tasks with configurable concurrency limits
+- Clean context manager support for resource management
+
+**Example**:
+
+```python
+from nodetool.concurrency.async_utils import AsyncSemaphore, gather_with_concurrency
+
+# Rate limiting with timeout
+sem = AsyncSemaphore(max_tasks=5)
+if await sem.acquire(timeout=10.0):
+    try:
+        await do_concurrent_work()
+    finally:
+        sem.release()
+
+# Context manager pattern
+async with AsyncSemaphore(max_tasks=3):
+    await do_work()
+
+# Batched execution with concurrency limit
+results = await gather_with_concurrency(
+    [fetch_url(url) for url in urls],
+    max_concurrent=10
+)
+```
+
+**Impact**: Provides reusable async utilities that follow the codebase's async-first patterns and DI conventions.
+
+**Files**:
+- `src/nodetool/concurrency/async_utils.py`
+- `src/nodetool/concurrency/__init__.py`
+- `tests/concurrency/test_async_utils.py`
+
+**Date**: 2026-01-12

nodetool_core-0.7.0/.github/opencode-memory/insights/async/async-flat-map-utility.md

@@ -0,0 +1,43 @@
+# async_flat_map Utility
+
+**Insight**: Flat mapping is a common pattern for one-to-many transformations on async iterables, combining mapping and flattening into a single operation.
+
+**Rationale**: When working with async iterables, it's common to need to transform each element into multiple elements (e.g., splitting a string into characters, expanding a range, or processing nested data structures). The `async_flat_map` utility provides a composable way to handle this pattern without intermediate list allocations.
+
+**Example**:
+```python
+from nodetool.concurrency import async_flat_map, async_list
+
+# Split each number into a range
+async def split(x):
+    for j in range(x):
+        yield j
+
+async def gen():
+    for i in range(3):
+        yield i
+
+result = await async_list(async_flat_map(split, gen()))
+# Result: [0, 0, 1] (split(0)=[], split(1)=[0], split(2)=[0, 1])
+
+# Flatten nested lists
+async def flatten(lst):
+    for item in lst:
+        yield item
+
+async def nested_gen():
+    for lst in [[1, 2], [3, 4, 5], [6]]:
+        yield lst
+
+result = await async_list(async_flat_map(flatten, nested_gen()))
+# Result: [1, 2, 3, 4, 5, 6]
+```
+
+**Impact**: Reduces code complexity for common async iterable transformations and provides a consistent API with other async iterator utilities like `async_map` and `async_filter`.
+
+**Files**:
+- `src/nodetool/concurrency/async_iterators.py`: Implementation
+- `src/nodetool/concurrency/__init__.py`: Export
+- `tests/concurrency/test_async_iterators.py`: Test coverage (13 tests)
+
+**Date**: 2026-02-09

nodetool_core-0.7.0/.github/opencode-memory/insights/async/async-iterator-utilities.md

@@ -0,0 +1,35 @@
+# Async Iterator Utilities
+
+**Insight**: Added utility functions for working with async iterables in `src/nodetool/concurrency/async_iterators.py`: `async_take`, `async_slice`, `async_first`, `async_list`, and `async_merge`.
+
+**Rationale**: While Python 3.11+ has excellent async iterator support, common operations like taking the first N items, slicing, or consuming to a list require boilerplate code. These utilities provide familiar functional programming patterns for async iterables, making async code more readable and maintainable.
+
+**Example**:
+
+```python
+from nodetool.concurrency import async_take, async_first, async_list, async_merge
+
+# Take first N items from an async generator
+first_5 = await async_take(async_generator(), 5)
+
+# Get just the first item (with optional default)
+first = await async_first(async_generator(), default=None)
+
+# Slice async iterables like lists
+items_5_to_10 = await async_slice(async_generator(), 5, 10)
+
+# Consume to list
+all_items = await async_list(async_generator())
+
+# Merge multiple async iterables sequentially
+combined = await async_list(async_merge(gen1(), gen2(), gen3()))
+```
+
+**Impact**: Provides reusable async iterator utilities that follow the codebase's async-first patterns. Reduces boilerplate code when working with async generators and iterables. All utilities are fully type-hinted with Generic TypeVar support for better IDE autocomplete and type checking.
+
+**Files**:
+- `src/nodetool/concurrency/async_iterators.py` - Added utility functions
+- `src/nodetool/concurrency/__init__.py` - Updated exports
+- `tests/concurrency/test_async_iterators.py` - 29 new tests covering all utilities
+
+**Date**: 2026-02-08