fengming 0.3.10 → 0.3.12

package/docs/tools/pdf.md

@@ -1,213 +0,0 @@
----
-summary: "Analyze one or more PDF documents with native provider support and extraction fallback"
-title: "PDF tool"
-read_when:
-  - You want to analyze PDFs from agents
-  - You need exact pdf tool parameters and limits
-  - You are debugging native PDF mode vs extraction fallback
----
-
-`pdf` analyzes one or more PDF documents and returns text.
-
-Quick behavior:
-
-- Native provider mode for Anthropic and Google model providers.
-- Extraction fallback mode for other providers (extract text first, then page images when needed).
-- Supports single (`pdf`) or multi (`pdfs`) input, max 10 PDFs per call.
-
-## Availability
-
-The tool is only registered when FengMing can resolve a PDF-capable model config for the agent:
-
-1. `agents.defaults.pdfModel`
-2. fallback to `agents.defaults.imageModel`
-3. fallback to the agent's resolved session/default model
-4. if native-PDF providers are auth-backed, prefer them ahead of generic image fallback candidates
-
-If no usable model can be resolved, the `pdf` tool is not exposed.
-
-Availability notes:
-
-- The fallback chain is auth-aware. A configured `provider/model` only counts if
-  FengMing can actually authenticate that provider for the agent.
-- Native PDF providers are currently **Anthropic** and **Google**.
-- If the resolved session/default provider already has a configured vision/PDF
-  model, the PDF tool reuses that before falling back to other auth-backed
-  providers.
-
-## Input reference
-
-<ParamField path="pdf" type="string">
-One PDF path or URL.
-</ParamField>
-
-<ParamField path="pdfs" type="string[]">
-Multiple PDF paths or URLs, up to 10 total.
-</ParamField>
-
-<ParamField path="prompt" type="string" default="Analyze this PDF document.">
-Analysis prompt.
-</ParamField>
-
-<ParamField path="pages" type="string">
-Page filter like `1-5` or `1,3,7-9`.
-</ParamField>
-
-<ParamField path="password" type="string">
-Password for encrypted PDFs in extraction fallback mode.
-</ParamField>
-
-<ParamField path="model" type="string">
-Optional model override in `provider/model` form.
-</ParamField>
-
-<ParamField path="maxBytesMb" type="number">
-Per-PDF size cap in MB. Defaults to `agents.defaults.pdfMaxBytesMb` or `10`.
-</ParamField>
-
-Input notes:
-
-- `pdf` and `pdfs` are merged and deduplicated before loading.
-- If no PDF input is provided, the tool errors.
-- `pages` is parsed as 1-based page numbers, deduped, sorted, and clamped to the configured max pages.
-- `password` applies to every PDF in the request and is only used by extraction fallback mode.
-- `maxBytesMb` defaults to `agents.defaults.pdfMaxBytesMb` or `10`.
-
-## Supported PDF references
-
-- local file path (including `~` expansion)
-- `file://` URL
-- `http://` and `https://` URL
-- FengMing-managed inbound refs such as `media://inbound/<id>`
-
-Reference notes:
-
-- Other URI schemes (for example `ftp://`) are rejected with `unsupported_pdf_reference`.
-- In sandbox mode, remote `http(s)` URLs are rejected.
-- With workspace-only file policy enabled, local file paths outside allowed roots are rejected.
-- Managed inbound refs and replayed paths under FengMing's inbound media store are allowed with workspace-only file policy.
-
-## Execution modes
-
-### Native provider mode
-
-Native mode is used for provider `anthropic` and `google`.
-The tool sends raw PDF bytes directly to provider APIs.
-
-Native mode limits:
-
-- `pages` is not supported. If set, the tool returns an error.
-- `password` is not supported. Use a non-native model to analyze encrypted PDFs.
-- Multi-PDF input is supported; each PDF is sent as a native document block /
-  inline PDF part before the prompt.
-
-### Extraction fallback mode
-
-Fallback mode is used for non-native providers.
-
-Flow:
-
-1. Extract text from selected pages (up to `agents.defaults.pdfMaxPages`, default `20`).
-2. If extracted text length is below `200` chars, render selected pages to PNG images and include them.
-3. Send extracted content plus prompt to the selected model.
-
-Fallback details:
-
-- Page image extraction uses a pixel budget of `4,000,000`.
-- Encrypted PDFs can be opened with the top-level `password` parameter.
-- If the target model does not support image input and there is no extractable text, the tool errors.
-- If text extraction succeeds but image extraction would require vision on a
-  text-only model, FengMing drops the rendered images and continues with the
-  extracted text.
-- Extraction fallback uses the bundled `document-extract` plugin. The plugin owns
-  `clawpdf`, which provides text extraction and image rendering through PDFium
-  WebAssembly.
-
-## Config
-
-```json5
-{
-  agents: {
-    defaults: {
-      pdfModel: {
-        primary: "anthropic/claude-opus-4-6",
-        fallbacks: ["openai/gpt-5.4-mini"],
-      },
-      pdfMaxBytesMb: 10,
-      pdfMaxPages: 20,
-    },
-  },
-}
-```
-
-See [Configuration Reference](/gateway/configuration-reference) for full field details.
-
-## Output details
-
-The tool returns text in `content[0].text` and structured metadata in `details`.
-
-Common `details` fields:
-
-- `model`: resolved model ref (`provider/model`)
-- `native`: `true` for native provider mode, `false` for fallback
-- `attempts`: fallback attempts that failed before success
-
-Path fields:
-
-- single PDF input: `details.pdf`
-- multiple PDF inputs: `details.pdfs[]` with `pdf` entries
-- sandbox path rewrite metadata (when applicable): `rewrittenFrom`
-
-## Error behavior
-
-- Missing PDF input: throws `pdf required: provide a path or URL to a PDF document`
-- Too many PDFs: returns structured error in `details.error = "too_many_pdfs"`
-- Unsupported reference scheme: returns `details.error = "unsupported_pdf_reference"`
-- Native mode with `pages`: throws clear `pages is not supported with native PDF providers` error
-
-## Examples
-
-Single PDF:
-
-```json
-{
-  "pdf": "/tmp/report.pdf",
-  "prompt": "Summarize this report in 5 bullets"
-}
-```
-
-Multiple PDFs:
-
-```json
-{
-  "pdfs": ["/tmp/q1.pdf", "/tmp/q2.pdf"],
-  "prompt": "Compare risks and timeline changes across both documents"
-}
-```
-
-Page-filtered fallback model:
-
-```json
-{
-  "pdf": "https://example.com/report.pdf",
-  "pages": "1-3,7",
-  "model": "openai/gpt-5.4-mini",
-  "prompt": "Extract only customer-impacting incidents"
-}
-```
-
-Encrypted PDF with extraction fallback:
-
-```json
-{
-  "pdf": "/tmp/locked.pdf",
-  "password": "example-password",
-  "model": "openai/gpt-5.4-mini",
-  "prompt": "Summarize this contract"
-}
-```
-
-## Related
-
-- [Tools Overview](/tools) - all available agent tools
-- [Configuration Reference](/gateway/config-agents#agent-defaults) - pdfMaxBytesMb and pdfMaxPages config

package/docs/tools/perplexity-search.md

@@ -1,220 +0,0 @@
----
-summary: "Perplexity Search API and Sonar/OpenRouter compatibility for web_search"
-read_when:
-  - You want to use Perplexity Search for web search
-  - You need PERPLEXITY_API_KEY or OPENROUTER_API_KEY setup
-title: "Perplexity search"
----
-
-FengMing supports Perplexity Search API as a `web_search` provider.
-It returns structured results with `title`, `url`, and `snippet` fields.
-
-For compatibility, FengMing also supports legacy Perplexity Sonar/OpenRouter setups.
-If you use `OPENROUTER_API_KEY`, an `sk-or-...` key in `plugins.entries.perplexity.config.webSearch.apiKey`, or set `plugins.entries.perplexity.config.webSearch.baseUrl` / `model`, the provider switches to the chat-completions path and returns AI-synthesized answers with citations instead of structured Search API results.
-
-## Getting a Perplexity API key
-
-1. Create a Perplexity account at [perplexity.ai/settings/api](https://www.perplexity.ai/settings/api)
-2. Generate an API key in the dashboard
-3. Store the key in config or set `PERPLEXITY_API_KEY` in the Gateway environment.
-
-## OpenRouter compatibility
-
-If you were already using OpenRouter for Perplexity Sonar, keep `provider: "perplexity"` and set `OPENROUTER_API_KEY` in the Gateway environment, or store an `sk-or-...` key in `plugins.entries.perplexity.config.webSearch.apiKey`.
-
-Optional compatibility controls:
-
-- `plugins.entries.perplexity.config.webSearch.baseUrl`
-- `plugins.entries.perplexity.config.webSearch.model`
-
-## Config examples
-
-### Native Perplexity Search API
-
-```json5
-{
-  plugins: {
-    entries: {
-      perplexity: {
-        config: {
-          webSearch: {
-            apiKey: "pplx-...",
-          },
-        },
-      },
-    },
-  },
-  tools: {
-    web: {
-      search: {
-        provider: "perplexity",
-      },
-    },
-  },
-}
-```
-
-### OpenRouter / Sonar compatibility
-
-```json5
-{
-  plugins: {
-    entries: {
-      perplexity: {
-        config: {
-          webSearch: {
-            apiKey: "<openrouter-api-key>",
-            baseUrl: "https://openrouter.ai/api/v1",
-            model: "perplexity/sonar-pro",
-          },
-        },
-      },
-    },
-  },
-  tools: {
-    web: {
-      search: {
-        provider: "perplexity",
-      },
-    },
-  },
-}
-```
-
-## Where to set the key
-
-**Via config:** run `fengming configure --section web`. It stores the key in
-`~/.fengming/fengming.json` under `plugins.entries.perplexity.config.webSearch.apiKey`.
-That field also accepts SecretRef objects.
-
-**Via environment:** set `PERPLEXITY_API_KEY` or `OPENROUTER_API_KEY`
-in the Gateway process environment. For a gateway install, put it in
-`~/.fengming/.env` (or your service environment). See [Env vars](/help/faq#env-vars-and-env-loading).
-
-If `provider: "perplexity"` is configured and the Perplexity key SecretRef is unresolved with no env fallback, startup/reload fails fast.
-
-## Tool parameters
-
-These parameters apply to the native Perplexity Search API path.
-
-<ParamField path="query" type="string" required>
-Search query.
-</ParamField>
-
-<ParamField path="count" type="number" default="5">
-Number of results to return (1-10).
-</ParamField>
-
-<ParamField path="country" type="string">
-2-letter ISO country code (e.g. `US`, `DE`).
-</ParamField>
-
-<ParamField path="language" type="string">
-ISO 639-1 language code (e.g. `en`, `de`, `fr`).
-</ParamField>
-
-<ParamField path="freshness" type="'day' | 'week' | 'month' | 'year'">
-Time filter - `day` is 24 hours.
-</ParamField>
-
-<ParamField path="date_after" type="string">
-Only results published after this date (`YYYY-MM-DD`).
-</ParamField>
-
-<ParamField path="date_before" type="string">
-Only results published before this date (`YYYY-MM-DD`).
-</ParamField>
-
-<ParamField path="domain_filter" type="string[]">
-Domain allowlist/denylist array (max 20).
-</ParamField>
-
-<ParamField path="max_tokens" type="number" default="25000">
-Total content budget (max 1000000).
-</ParamField>
-
-<ParamField path="max_tokens_per_page" type="number" default="2048">
-Per-page token limit.
-</ParamField>
-
-For the legacy Sonar/OpenRouter compatibility path:
-
-- `query`, `count`, and `freshness` are accepted
-- `count` is compatibility-only there; the response is still one synthesized
-  answer with citations rather than an N-result list
-- Search API-only filters such as `country`, `language`, `date_after`,
-  `date_before`, `domain_filter`, `max_tokens`, and `max_tokens_per_page`
-  return explicit errors
-
-**Examples:**
-
-```javascript
-// Country and language-specific search
-await web_search({
-  query: "renewable energy",
-  country: "DE",
-  language: "de",
-});
-
-// Recent results (past week)
-await web_search({
-  query: "AI news",
-  freshness: "week",
-});
-
-// Date range search
-await web_search({
-  query: "AI developments",
-  date_after: "2024-01-01",
-  date_before: "2024-06-30",
-});
-
-// Domain filtering (allowlist)
-await web_search({
-  query: "climate research",
-  domain_filter: ["nature.com", "science.org", ".edu"],
-});
-
-// Domain filtering (denylist - prefix with -)
-await web_search({
-  query: "product reviews",
-  domain_filter: ["-reddit.com", "-pinterest.com"],
-});
-
-// More content extraction
-await web_search({
-  query: "detailed AI research",
-  max_tokens: 50000,
-  max_tokens_per_page: 4096,
-});
-```
-
-### Domain filter rules
-
-- Maximum 20 domains per filter
-- Cannot mix allowlist and denylist in the same request
-- Use `-` prefix for denylist entries (e.g., `["-reddit.com"]`)
-
-## Notes
-
-- Perplexity Search API returns structured web search results (`title`, `url`, `snippet`)
-- OpenRouter or explicit `plugins.entries.perplexity.config.webSearch.baseUrl` / `model` switches Perplexity back to Sonar chat completions for compatibility
-- Sonar/OpenRouter compatibility returns one synthesized answer with citations, not structured result rows
-- Results are cached for 15 minutes by default (configurable via `cacheTtlMinutes`)
-
-## Related
-
-<CardGroup cols={2}>
-  <Card title="Web search overview" href="/tools/web" icon="globe">
-    All providers and auto-detection rules.
-  </Card>
-  <Card title="Brave search" href="/tools/brave-search" icon="shield">
-    Structured results with country and language filters.
-  </Card>
-  <Card title="Exa search" href="/tools/exa-search" icon="magnifying-glass">
-    Neural search with content extraction.
-  </Card>
-  <Card title="Perplexity Search API docs" href="https://docs.perplexity.ai/docs/search/quickstart" icon="arrow-up-right-from-square">
-    Official Perplexity Search API quickstart and reference.
-  </Card>
-</CardGroup>