better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/research/research-parallel-cli.md

@@ -0,0 +1,411 @@
+---
+title: "Parallel Cli — Agent-native web search, deep research, and enrichment"
+sidebar_label: "Parallel Cli"
+description: "Agent-native web search, deep research, and enrichment"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Parallel Cli
+
+Agent-native web search, deep research, and enrichment.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/research/parallel-cli` |
+| Path | `optional-skills/research\parallel-cli` |
+| Version | `1.1.0` |
+| Author | Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `Research`, `Web`, `Search`, `Deep-Research`, `Enrichment`, `CLI` |
+| Related skills | [`duckduckgo-search`](/docs/user-guide/skills/optional/research/research-duckduckgo-search), [`mcporter`](/docs/user-guide/skills/optional/mcp/mcp-mcporter) |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# Parallel CLI
+
+Use `parallel-cli` when the user explicitly wants Parallel, or when a terminal-native workflow would benefit from Parallel's vendor-specific stack for web search, extraction, deep research, enrichment, entity discovery, or monitoring.
+
+This is an optional third-party workflow, not a Hermes core capability.
+
+Important expectations:
+- Parallel is a paid service with a free tier, not a fully free local tool.
+- It overlaps with Hermes native `web_search` / `web_extract`, so do not prefer it by default for ordinary lookups.
+- Prefer this skill when the user mentions Parallel specifically or needs capabilities like Parallel's enrichment, FindAll, or monitor workflows.
+
+`parallel-cli` is designed for agents:
+- JSON output via `--json`
+- Non-interactive command execution
+- Async long-running jobs with `--no-wait`, `status`, and `poll`
+- Context chaining with `--previous-interaction-id`
+- Search, extract, research, enrichment, entity discovery, and monitoring in one CLI
+
+## When to use it
+
+Prefer this skill when:
+- The user explicitly mentions Parallel or `parallel-cli`
+- The task needs richer workflows than a simple one-shot search/extract pass
+- You need async deep research jobs that can be launched and polled later
+- You need structured enrichment, FindAll entity discovery, or monitoring
+
+Prefer Hermes native `web_search` / `web_extract` for quick one-off lookups when Parallel is not specifically requested.
+
+## Installation
+
+Try the least invasive install path available for the environment.
+
+### Homebrew
+
+```bash
+brew install parallel-web/tap/parallel-cli
+```
+
+### npm
+
+```bash
+npm install -g parallel-web-cli
+```
+
+### Python package
+
+```bash
+pip install "parallel-web-tools[cli]"
+```
+
+### Standalone installer
+
+```bash
+curl -fsSL https://parallel.ai/install.sh | bash
+```
+
+If you want an isolated Python install, `pipx` can also work:
+
+```bash
+pipx install "parallel-web-tools[cli]"
+pipx ensurepath
+```
+
+## Authentication
+
+Interactive login:
+
+```bash
+parallel-cli login
+```
+
+Headless / SSH / CI:
+
+```bash
+parallel-cli login --device
+```
+
+API key environment variable:
+
+```bash
+export PARALLEL_API_KEY="***"
+```
+
+Verify current auth status:
+
+```bash
+parallel-cli auth
+```
+
+If auth requires browser interaction, run with `pty=true`.
+
+## Core rule set
+
+1. Always prefer `--json` when you need machine-readable output.
+2. Prefer explicit arguments and non-interactive flows.
+3. For long-running jobs, use `--no-wait` and then `status` / `poll`.
+4. Cite only URLs returned by the CLI output.
+5. Save large JSON outputs to a temp file when follow-up questions are likely.
+6. Use background processes only for genuinely long-running workflows; otherwise run in foreground.
+7. Prefer Hermes native tools unless the user wants Parallel specifically or needs Parallel-only workflows.
+
+## Quick reference
+
+<!-- ascii-guard-ignore -->
+```text
+parallel-cli
+├── auth
+├── login
+├── logout
+├── search
+├── extract / fetch
+├── research run|status|poll|processors
+├── enrich run|status|poll|plan|suggest|deploy
+├── findall run|ingest|status|poll|result|enrich|extend|schema|cancel
+└── monitor create|list|get|update|delete|events|event-group|simulate
+```
+<!-- ascii-guard-ignore-end -->
+
+## Common flags and patterns
+
+Commonly useful flags:
+- `--json` for structured output
+- `--no-wait` for async jobs
+- `--previous-interaction-id <id>` for follow-up tasks that reuse earlier context
+- `--max-results <n>` for search result count
+- `--mode one-shot|agentic` for search behavior
+- `--include-domains domain1.com,domain2.com`
+- `--exclude-domains domain1.com,domain2.com`
+- `--after-date YYYY-MM-DD`
+
+Read from stdin when convenient:
+
+```bash
+echo "What is the latest funding for Anthropic?" | parallel-cli search - --json
+echo "Research question" | parallel-cli research run - --json
+```
+
+## Search
+
+Use for current web lookups with structured results.
+
+```bash
+parallel-cli search "What is Anthropic's latest AI model?" --json
+parallel-cli search "SEC filings for Apple" --include-domains sec.gov --json
+parallel-cli search "bitcoin price" --after-date 2026-01-01 --max-results 10 --json
+parallel-cli search "latest browser benchmarks" --mode one-shot --json
+parallel-cli search "AI coding agent enterprise reviews" --mode agentic --json
+```
+
+Useful constraints:
+- `--include-domains` to narrow trusted sources
+- `--exclude-domains` to strip noisy domains
+- `--after-date` for recency filtering
+- `--max-results` when you need broader coverage
+
+If you expect follow-up questions, save output:
+
+```bash
+parallel-cli search "latest React 19 changes" --json -o /tmp/react-19-search.json
+```
+
+When summarizing results:
+- lead with the answer
+- include dates, names, and concrete facts
+- cite only returned sources
+- avoid inventing URLs or source titles
+
+## Extraction
+
+Use to pull clean content or markdown from a URL.
+
+```bash
+parallel-cli extract https://example.com --json
+parallel-cli extract https://company.com --objective "Find pricing info" --json
+parallel-cli extract https://example.com --full-content --json
+parallel-cli fetch https://example.com --json
+```
+
+Use `--objective` when the page is broad and you only need one slice of information.
+
+## Deep research
+
+Use for deeper multi-step research tasks that may take time.
+
+Common processor tiers:
+- `lite` / `base` for faster, cheaper passes
+- `core` / `pro` for more thorough synthesis
+- `ultra` for the heaviest research jobs
+
+### Synchronous
+
+```bash
+parallel-cli research run \
+  "Compare the leading AI coding agents by pricing, model support, and enterprise controls" \
+  --processor core \
+  --json
+```
+
+### Async launch + poll
+
+```bash
+parallel-cli research run \
+  "Compare the leading AI coding agents by pricing, model support, and enterprise controls" \
+  --processor ultra \
+  --no-wait \
+  --json
+
+parallel-cli research status trun_xxx --json
+parallel-cli research poll trun_xxx --json
+parallel-cli research processors --json
+```
+
+### Context chaining / follow-up
+
+```bash
+parallel-cli research run "What are the top AI coding agents?" --json
+parallel-cli research run \
+  "What enterprise controls does the top-ranked one offer?" \
+  --previous-interaction-id trun_xxx \
+  --json
+```
+
+Recommended Hermes workflow:
+1. launch with `--no-wait --json`
+2. capture the returned run/task ID
+3. if the user wants to continue other work, keep moving
+4. later call `status` or `poll`
+5. summarize the final report with citations from the returned sources
+
+## Enrichment
+
+Use when the user has CSV/JSON/tabular inputs and wants additional columns inferred from web research.
+
+### Suggest columns
+
+```bash
+parallel-cli enrich suggest "Find the CEO and annual revenue" --json
+```
+
+### Plan a config
+
+```bash
+parallel-cli enrich plan -o config.yaml
+```
+
+### Inline data
+
+```bash
+parallel-cli enrich run \
+  --data '[{"company": "Anthropic"}, {"company": "Mistral"}]' \
+  --intent "Find headquarters and employee count" \
+  --json
+```
+
+### Non-interactive file run
+
+```bash
+parallel-cli enrich run \
+  --source-type csv \
+  --source companies.csv \
+  --target enriched.csv \
+  --source-columns '[{"name": "company", "description": "Company name"}]' \
+  --intent "Find the CEO and annual revenue"
+```
+
+### YAML config run
+
+```bash
+parallel-cli enrich run config.yaml
+```
+
+### Status / polling
+
+```bash
+parallel-cli enrich status <task_group_id> --json
+parallel-cli enrich poll <task_group_id> --json
+```
+
+Use explicit JSON arrays for column definitions when operating non-interactively.
+Validate the output file before reporting success.
+
+## FindAll
+
+Use for web-scale entity discovery when the user wants a discovered dataset rather than a short answer.
+
+```bash
+parallel-cli findall run "Find AI coding agent startups with enterprise offerings" --json
+parallel-cli findall run "AI startups in healthcare" -n 25 --json
+parallel-cli findall status <run_id> --json
+parallel-cli findall poll <run_id> --json
+parallel-cli findall result <run_id> --json
+parallel-cli findall schema <run_id> --json
+```
+
+This is a better fit than ordinary search when the user wants a discovered set of entities that can be reviewed, filtered, or enriched later.
+
+## Monitor
+
+Use for ongoing change detection over time.
+
+```bash
+parallel-cli monitor list --json
+parallel-cli monitor get <monitor_id> --json
+parallel-cli monitor events <monitor_id> --json
+parallel-cli monitor delete <monitor_id> --json
+```
+
+Creation is usually the sensitive part because cadence and delivery matter:
+
+```bash
+parallel-cli monitor create --help
+```
+
+Use this when the user wants recurring tracking of a page or source rather than a one-time fetch.
+
+## Recommended Hermes usage patterns
+
+### Fast answer with citations
+1. Run `parallel-cli search ... --json`
+2. Parse titles, URLs, dates, excerpts
+3. Summarize with inline citations from the returned URLs only
+
+### URL investigation
+1. Run `parallel-cli extract URL --json`
+2. If needed, rerun with `--objective` or `--full-content`
+3. Quote or summarize the extracted markdown
+
+### Long research workflow
+1. Run `parallel-cli research run ... --no-wait --json`
+2. Store the returned ID
+3. Continue other work or periodically poll
+4. Summarize the final report with citations
+
+### Structured enrichment workflow
+1. Inspect the input file and columns
+2. Use `enrich suggest` or provide explicit enriched columns
+3. Run `enrich run`
+4. Poll for completion if needed
+5. Validate the output file before reporting success
+
+## Error handling and exit codes
+
+The CLI documents these exit codes:
+- `0` success
+- `2` bad input
+- `3` auth error
+- `4` API error
+- `5` timeout
+
+If you hit auth errors:
+1. check `parallel-cli auth`
+2. confirm `PARALLEL_API_KEY` or run `parallel-cli login` / `parallel-cli login --device`
+3. verify `parallel-cli` is on `PATH`
+
+## Maintenance
+
+Check current auth / install state:
+
+```bash
+parallel-cli auth
+parallel-cli --help
+```
+
+Update commands:
+
+```bash
+parallel-cli update
+pip install --upgrade parallel-web-tools
+parallel-cli config auto-update-check off
+```
+
+## Pitfalls
+
+- Do not omit `--json` unless the user explicitly wants human-formatted output.
+- Do not cite sources not present in the CLI output.
+- `login` may require PTY/browser interaction.
+- Prefer foreground execution for short tasks; do not overuse background processes.
+- For large result sets, save JSON to `/tmp/*.json` instead of stuffing everything into context.
+- Do not silently choose Parallel when Hermes native tools are already sufficient.
+- Remember this is a vendor workflow that usually requires account auth and paid usage beyond the free tier.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/research/research-pinecone-research.md

@@ -0,0 +1,125 @@
+---
+title: "Pinecone Research — Agent RAG and long-term memory with Pinecone"
+sidebar_label: "Pinecone Research"
+description: "Agent RAG and long-term memory with Pinecone"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Pinecone Research
+
+Agent RAG and long-term memory with Pinecone.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/research/pinecone-research` |
+| Path | `optional-skills/research\pinecone-research` |
+| Version | `1.0.0` |
+| Author | immuhammadfurqan |
+| License | MIT |
+| Dependencies | `pinecone-client`, `langchain-pinecone` |
+| Platforms | linux, macos, windows |
+| Tags | `RAG`, `Pinecone`, `Memory`, `Research`, `Vector Database`, `Agent`, `Retrieval` |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# Pinecone Research — Agent RAG & Long-Term Memory
+
+Use Pinecone as a retrieval-augmented generation (RAG) backend for agent
+conversations: persist embeddings, retrieve relevant context from past
+sessions, and build long-term memory.
+
+## When to use this skill
+
+**Use when:**
+- Building agent RAG pipelines with Pinecone as the vector store
+- Need persistent long-term memory across agent sessions
+- Combining retrieval with agent tool use
+- Researching or prototyping semantic search workflows
+
+**Use the mlops/pinecone skill instead when:**
+- Need a general Pinecone reference (index management, CRUD, hybrid search)
+- Working on production infrastructure without agent integration
+
+## Quick start
+
+### Setup
+
+```bash
+pip install pinecone-client langchain-pinecone langchain-openai
+```
+
+Set your API key:
+```bash
+export PINECONE_API_KEY="your-api-key"
+```
+
+### Basic RAG pipeline
+
+```python
+from pinecone import Pinecone, ServerlessSpec
+from langchain_pinecone import PineconeVectorStore
+from langchain_openai import OpenAIEmbeddings
+
+# Initialize Pinecone
+pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
+
+# Create or connect to index
+index_name = "agent-memory"
+if index_name not in [i.name for i in pc.list_indexes()]:
+    pc.create_index(
+        name=index_name,
+        dimension=1536,
+        metric="cosine",
+        spec=ServerlessSpec(cloud="aws", region="us-east-1"),
+    )
+
+# Build vector store
+vectorstore = PineconeVectorStore.from_documents(
+    documents=docs,
+    embedding=OpenAIEmbeddings(),
+    index_name=index_name,
+)
+
+# Retrieve relevant context
+retriever = vectorstore.as_retriever(search_kwargs={"k": 5})
+results = retriever.invoke("What did the agent discuss yesterday?")
+```
+
+### Namespace-based session memory
+
+```python
+# Store per-session memory
+vectorstore = PineconeVectorStore(
+    index=pc.Index(index_name),
+    embedding=OpenAIEmbeddings(),
+    namespace=f"session-{session_id}",
+)
+
+# Query across all sessions (no namespace filter)
+all_memory = PineconeVectorStore(
+    index=pc.Index(index_name),
+    embedding=OpenAIEmbeddings(),
+)
+results = all_memory.similarity_search("relevant query", k=10)
+```
+
+## Best practices
+
+1. **Namespace by session or user** — isolate data for multi-tenant agents
+2. **Batch upserts** — 100–200 vectors per batch for efficiency
+3. **Metadata filtering** — tag vectors with session ID, timestamp, topic
+4. **Prune old memory** — delete stale namespaces to control costs
+5. **Use serverless** — auto-scaling, pay-per-use pricing
+
+## Resources
+
+- **Pinecone Docs**: https://docs.pinecone.io
+- **LangChain Integration**: https://python.langchain.com/docs/integrations/vectorstores/pinecone
+- **Free Tier**: 1 index, 100K vectors (1536 dimensions)