diff --git a/docs/docs/advanced/mellea-core-internals.md b/docs/docs/advanced/mellea-core-internals.md index 11f81a312..ff0ac06e2 100644 --- a/docs/docs/advanced/mellea-core-internals.md +++ b/docs/docs/advanced/mellea-core-internals.md @@ -277,5 +277,5 @@ for a worked example. **See also:** [Generative Programming](../concepts/generative-programming) | -[Working with Data](../guide/working-with-data) | +[Working with Data](../how-to/working-with-data) | [Async and Streaming](../how-to/use-async-and-streaming) diff --git a/docs/docs/concepts/architecture-vs-agents.md b/docs/docs/concepts/architecture-vs-agents.md index 405cf30bd..f223a74cb 100644 --- a/docs/docs/concepts/architecture-vs-agents.md +++ b/docs/docs/concepts/architecture-vs-agents.md @@ -133,13 +133,13 @@ orchestrator: - **ReACT loops** — implement thought/action/observation cycles using `m.chat()` with [`ChatContext`](../guide/glossary#chatcontext) and the `@tool` decorator. See - [Tools and Agents](../guide/tools-and-agents). + [Tools and Agents](../how-to/tools-and-agents). - **Guarded agents** — combine the ReACT pattern with `requirements` and `GuardianCheck` to enforce safety constraints at every step. See [Security and Taint Tracking](../advanced/security-and-taint-tracking). - **Structured outputs** — use `@generative` with Pydantic models or `Literal` types to enforce type-safe structured output at each step. See - [Generative Functions](../guide/generative-functions). + [Generative Functions](../how-to/generative-functions). For programs where the control flow is fixed in Python — a pipeline, an extraction workflow, a classification step — there is no need for a separate orchestrator. @@ -211,5 +211,5 @@ tools or steps. --- -**See also:** [Tools and Agents](../guide/tools-and-agents) | +**See also:** [Tools and Agents](../how-to/tools-and-agents) | [Security and Taint Tracking](../advanced/security-and-taint-tracking) diff --git a/docs/docs/concepts/generative-functions.md b/docs/docs/concepts/generative-functions.md index b9b79a91a..daa3e529d 100644 --- a/docs/docs/concepts/generative-functions.md +++ b/docs/docs/concepts/generative-functions.md @@ -9,7 +9,7 @@ In a generative program, a function can have the same interface but delegate its to an LLM. Mellea calls these [**generative functions**](../guide/glossary#generative-function) and provides the [`@generative`](../guide/glossary#generative) decorator to define them. -> **Looking to use this in code?** See [Generative Functions](../guide/generative-functions) for practical examples and API details. +> **Looking to use this in code?** See [Generative Functions](../how-to/generative-functions) for practical examples and API details. ## The @generative decorator @@ -167,4 +167,4 @@ Use `@generative` when you want a named, typed, reusable LLM-backed operation. U **See also:** [Instruct, Validate, Repair](./instruct-validate-repair) | [The Requirements System](./requirements-system) | -[Tools and Agents](../guide/tools-and-agents) +[Tools and Agents](../how-to/tools-and-agents) diff --git a/docs/docs/concepts/generative-programming.md b/docs/docs/concepts/generative-programming.md index 6094fb93d..bce66cdf8 100644 --- a/docs/docs/concepts/generative-programming.md +++ b/docs/docs/concepts/generative-programming.md @@ -143,4 +143,4 @@ These principles recur throughout Mellea: **See also:** [Instruct, Validate, Repair](./instruct-validate-repair) | [Inference-Time Scaling](../advanced/inference-time-scaling) | -[Working with Data](../guide/working-with-data) +[Working with Data](../how-to/working-with-data) diff --git a/docs/docs/concepts/instruct-validate-repair.md b/docs/docs/concepts/instruct-validate-repair.md index 72af31c51..4d7a80131 100644 --- a/docs/docs/concepts/instruct-validate-repair.md +++ b/docs/docs/concepts/instruct-validate-repair.md @@ -188,7 +188,7 @@ print(str(answer)) `grounding_context` maps string keys to document text. The keys are arbitrary labels — they appear in the prompt as `[key] = value` so the model can reference them by name, but there is no required naming convention (e.g. `"doc0"`, `"annual_report"`, -`"spec"` all work). See [Working with Data](../guide/working-with-data) for richer +`"spec"` all work). See [Working with Data](../how-to/working-with-data) for richer document handling using MObjects and `RichDocument`. ## ICL examples diff --git a/docs/docs/concepts/plugins.mdx b/docs/docs/concepts/plugins.mdx index e8c67fad9..04b0829ee 100644 --- a/docs/docs/concepts/plugins.mdx +++ b/docs/docs/concepts/plugins.mdx @@ -989,4 +989,4 @@ from mellea.plugins import ( --- -**See also:** [Glossary](../guide/glossary), [Tools and Agents](../guide/tools-and-agents), [Security and Taint Tracking](../advanced/security-and-taint-tracking), [OpenTelemetry Tracing](../evaluation-and-observability/opentelemetry-tracing) +**See also:** [Glossary](../guide/glossary), [Tools and Agents](../how-to/tools-and-agents), [Security and Taint Tracking](../advanced/security-and-taint-tracking), [OpenTelemetry Tracing](../evaluation-and-observability/opentelemetry-tracing) diff --git a/docs/docs/docs.json b/docs/docs/docs.json index 66af87e01..9f5524912 100644 --- a/docs/docs/docs.json +++ b/docs/docs/docs.json @@ -54,12 +54,12 @@ { "group": "How-To", "pages": [ - "guide/generative-functions", - "guide/tools-and-agents", - "guide/working-with-data", - "guide/backends-and-configuration", - "guide/act-and-aact", - "guide/m-decompose", + "how-to/generative-functions", + "how-to/tools-and-agents", + "how-to/working-with-data", + "how-to/backends-and-configuration", + "how-to/act-and-aact", + "how-to/m-decompose", "how-to/use-async-and-streaming", "how-to/use-context-and-sessions", "how-to/enforce-structured-output", @@ -443,7 +443,7 @@ }, { "source": "/overview/architecture", - "destination": "/guide/backends-and-configuration" + "destination": "/how-to/backends-and-configuration" }, { "source": "/core-concept/instruct-validate-repair", @@ -455,7 +455,7 @@ }, { "source": "/core-concept/generative-slots", - "destination": "/guide/generative-functions" + "destination": "/how-to/generative-functions" }, { "source": "/core-concept/mobjects", @@ -463,7 +463,7 @@ }, { "source": "/core-concept/agents", - "destination": "/guide/tools-and-agents" + "destination": "/how-to/tools-and-agents" }, { "source": "/core-concept/context-management", @@ -491,7 +491,7 @@ }, { "source": "/core-concept/adapters", - "destination": "/guide/tools-and-agents" + "destination": "/how-to/tools-and-agents" }, { "source": "/core-concept/contribution-guide", @@ -547,7 +547,7 @@ }, { "source": "/dev/tool-calling", - "destination": "/guide/tools-and-agents" + "destination": "/how-to/tools-and-agents" }, { "source": "/api/cli/m", @@ -616,6 +616,30 @@ { "source": "/api/cli/fix/genstub_fixer", "destination": "/reference/cli" + }, + { + "source": "/guide/generative-functions", + "destination": "/how-to/generative-functions" + }, + { + "source": "/guide/tools-and-agents", + "destination": "/how-to/tools-and-agents" + }, + { + "source": "/guide/working-with-data", + "destination": "/how-to/working-with-data" + }, + { + "source": "/guide/backends-and-configuration", + "destination": "/how-to/backends-and-configuration" + }, + { + "source": "/guide/act-and-aact", + "destination": "/how-to/act-and-aact" + }, + { + "source": "/guide/m-decompose", + "destination": "/how-to/m-decompose" } ] } diff --git a/docs/docs/examples/data-extraction-pipeline.md b/docs/docs/examples/data-extraction-pipeline.md index 054184f5d..cffbc0db2 100644 --- a/docs/docs/examples/data-extraction-pipeline.md +++ b/docs/docs/examples/data-extraction-pipeline.md @@ -35,7 +35,7 @@ m = start_session() `start_session()` with no arguments creates a session backed by the default local model. The `model_ids` import is available if you want to switch to a -specific model later (see [Backends and configuration](../guide/backends-and-configuration)). +specific model later (see [Backends and configuration](../how-to/backends-and-configuration)). ### Declaring the extraction function diff --git a/docs/docs/getting-started/quickstart.md b/docs/docs/getting-started/quickstart.md index f584cf5ba..1785bcf01 100644 --- a/docs/docs/getting-started/quickstart.md +++ b/docs/docs/getting-started/quickstart.md @@ -94,7 +94,7 @@ chat. **Backends** — Pluggable model providers. Ollama is the default. OpenAI, [LiteLLM](../guide/glossary#litellm--litellmbackend), HuggingFace, and WatsonX are also supported. See -[Backends and Configuration](../guide/backends-and-configuration). +[Backends and Configuration](../how-to/backends-and-configuration). ## Troubleshooting diff --git a/docs/docs/guide/CONTRIBUTING.md b/docs/docs/guide/CONTRIBUTING.md index d538e53ca..a22722a5c 100644 --- a/docs/docs/guide/CONTRIBUTING.md +++ b/docs/docs/guide/CONTRIBUTING.md @@ -74,7 +74,7 @@ before the first H2, so readers can orient themselves quickly: - On the **explanation** page: ```markdown - > **Looking to use this in code?** See [Generative Functions](../guide/generative-functions) for practical examples and API details. + > **Looking to use this in code?** See [Generative Functions](../how-to/generative-functions) for practical examples and API details. ``` - On the **how-to** page: diff --git a/docs/docs/guide/act-and-aact.md b/docs/docs/how-to/act-and-aact.md similarity index 100% rename from docs/docs/guide/act-and-aact.md rename to docs/docs/how-to/act-and-aact.md diff --git a/docs/docs/guide/backends-and-configuration.md b/docs/docs/how-to/backends-and-configuration.md similarity index 100% rename from docs/docs/guide/backends-and-configuration.md rename to docs/docs/how-to/backends-and-configuration.md diff --git a/docs/docs/how-to/enforce-structured-output.md b/docs/docs/how-to/enforce-structured-output.md index 4647d5271..1fe0ba412 100644 --- a/docs/docs/how-to/enforce-structured-output.md +++ b/docs/docs/how-to/enforce-structured-output.md @@ -260,5 +260,5 @@ Both patterns support the full IVR loop, requirements, sampling strategies, and --- -**See also:** [Generative Functions](../guide/generative-functions) | +**See also:** [Generative Functions](../how-to/generative-functions) | [The Requirements System](../concepts/requirements-system) diff --git a/docs/docs/guide/generative-functions.md b/docs/docs/how-to/generative-functions.md similarity index 100% rename from docs/docs/guide/generative-functions.md rename to docs/docs/how-to/generative-functions.md diff --git a/docs/docs/guide/m-decompose.md b/docs/docs/how-to/m-decompose.md similarity index 95% rename from docs/docs/guide/m-decompose.md rename to docs/docs/how-to/m-decompose.md index d3c241713..056bdbb40 100644 --- a/docs/docs/guide/m-decompose.md +++ b/docs/docs/how-to/m-decompose.md @@ -123,4 +123,4 @@ For tasks that fit comfortably in a single prompt, use `m.instruct()` directly. --- -**See also:** [Tools and Agents](../guide/tools-and-agents) | [Refactor Prompts with CLI](../how-to/refactor-prompts-with-cli) | [CLI Reference](../reference/cli) +**See also:** [Tools and Agents](../how-to/tools-and-agents) | [Refactor Prompts with CLI](../how-to/refactor-prompts-with-cli) | [CLI Reference](../reference/cli) diff --git a/docs/docs/guide/tools-and-agents.md b/docs/docs/how-to/tools-and-agents.md similarity index 100% rename from docs/docs/guide/tools-and-agents.md rename to docs/docs/how-to/tools-and-agents.md diff --git a/docs/docs/how-to/use-async-and-streaming.md b/docs/docs/how-to/use-async-and-streaming.md index defe982e6..39ed4ea5b 100644 --- a/docs/docs/how-to/use-async-and-streaming.md +++ b/docs/docs/how-to/use-async-and-streaming.md @@ -166,4 +166,4 @@ For parallel generation, use `SimpleContext`. --- -**See also:** [Tutorial 02: Streaming and Async](../tutorials/02-streaming-and-async) | [act() and aact()](../guide/act-and-aact) +**See also:** [Tutorial 02: Streaming and Async](../tutorials/02-streaming-and-async) | [act() and aact()](../how-to/act-and-aact) diff --git a/docs/docs/how-to/use-images-and-vision.md b/docs/docs/how-to/use-images-and-vision.md index 0c1630313..6efdbaf1b 100644 --- a/docs/docs/how-to/use-images-and-vision.md +++ b/docs/docs/how-to/use-images-and-vision.md @@ -121,5 +121,5 @@ To remove images from context on the next turn, pass `images=[]` explicitly. --- -**See also:** [Working with Data](../guide/working-with-data) | +**See also:** [Working with Data](../how-to/working-with-data) | [The Instruction Model](../concepts/instruct-validate-repair) diff --git a/docs/docs/guide/working-with-data.md b/docs/docs/how-to/working-with-data.md similarity index 98% rename from docs/docs/guide/working-with-data.md rename to docs/docs/how-to/working-with-data.md index ce16ae2a5..94a993d8b 100644 --- a/docs/docs/guide/working-with-data.md +++ b/docs/docs/how-to/working-with-data.md @@ -250,4 +250,4 @@ tools during `transform()` calls automatically. --- -**See also:** [act() and aact()](../guide/act-and-aact) | [MObjects and mify](../concepts/mobjects-and-mify) +**See also:** [act() and aact()](../how-to/act-and-aact) | [MObjects and mify](../concepts/mobjects-and-mify) diff --git a/docs/docs/index.mdx b/docs/docs/index.mdx index 6ddccaf2e..5c10173e8 100644 --- a/docs/docs/index.mdx +++ b/docs/docs/index.mdx @@ -72,7 +72,7 @@ Mellea's design rests on three interlocking ideas. Best-of-n, SOFAI, majority voting — swap strategies in one line. - + `@tool`, `MelleaTool`, and the ReACT loop for goal-driven multi-step agents. @@ -105,7 +105,7 @@ Mellea is backend-agnostic. The same program runs on any inference engine. -See [Backends and configuration](/guide/backends-and-configuration) for the full list of supported backends and how to configure them. +See [Backends and configuration](/how-to/backends-and-configuration) for the full list of supported backends and how to configure them. ## How-to guides diff --git a/docs/docs/integrations/bedrock.md b/docs/docs/integrations/bedrock.md index 8c38b0939..da55b77d7 100644 --- a/docs/docs/integrations/bedrock.md +++ b/docs/docs/integrations/bedrock.md @@ -145,4 +145,4 @@ so vision-capable models (e.g., `amazon.nova-pro-v1:0`) support image input via --- -**See also:** [Backends and Configuration](../guide/backends-and-configuration) +**See also:** [Backends and Configuration](../how-to/backends-and-configuration) diff --git a/docs/docs/integrations/huggingface.md b/docs/docs/integrations/huggingface.md index 363c77378..f9d27c036 100644 --- a/docs/docs/integrations/huggingface.md +++ b/docs/docs/integrations/huggingface.md @@ -115,5 +115,5 @@ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh --- -**See also:** [Backends and Configuration](../guide/backends-and-configuration) | +**See also:** [Backends and Configuration](../how-to/backends-and-configuration) | [LoRA and aLoRA Adapters](../advanced/lora-and-alora-adapters) diff --git a/docs/docs/integrations/langchain.md b/docs/docs/integrations/langchain.md index 5a5a18ddf..8851d1ecb 100644 --- a/docs/docs/integrations/langchain.md +++ b/docs/docs/integrations/langchain.md @@ -105,11 +105,11 @@ OpenAI chat format — LlamaIndex, Haystack, Semantic Kernel — works with the | -------- | --- | | Your tool exists as a LangChain `BaseTool` | `MelleaTool.from_langchain(tool)` | | Your tool exists as a smolagents `Tool` | [`MelleaTool.from_smolagents(tool)`](./smolagents) | -| You have a plain Python function to expose | [`@tool` decorator](../guide/tools-and-agents) | +| You have a plain Python function to expose | [`@tool` decorator](../how-to/tools-and-agents) | | You have LangChain message history to continue | `convert_to_openai_messages` → `ChatContext` | | You want Mellea as an OpenAI endpoint for another framework | [`m serve`](./m-serve) | --- -**See also:** [Tools and Agents](../guide/tools-and-agents) | +**See also:** [Tools and Agents](../how-to/tools-and-agents) | [Context and Sessions](../concepts/context-and-sessions) diff --git a/docs/docs/integrations/m-serve.md b/docs/docs/integrations/m-serve.md index 3999e3f3a..99643ffef 100644 --- a/docs/docs/integrations/m-serve.md +++ b/docs/docs/integrations/m-serve.md @@ -112,5 +112,5 @@ print(response.choices[0].message.content) --- **See also:** [Context and Sessions](../concepts/context-and-sessions) | -[Backends and Configuration](../guide/backends-and-configuration) | +[Backends and Configuration](../how-to/backends-and-configuration) | [CLI Reference](../reference/cli) diff --git a/docs/docs/integrations/mcp.md b/docs/docs/integrations/mcp.md index edd232cd7..a7b93d91a 100644 --- a/docs/docs/integrations/mcp.md +++ b/docs/docs/integrations/mcp.md @@ -115,4 +115,4 @@ uv run your_server.py --- -**See also:** [Backends and Configuration](../guide/backends-and-configuration) +**See also:** [Backends and Configuration](../how-to/backends-and-configuration) diff --git a/docs/docs/integrations/ollama.md b/docs/docs/integrations/ollama.md index 690c9be03..d2ea667de 100644 --- a/docs/docs/integrations/ollama.md +++ b/docs/docs/integrations/ollama.md @@ -205,7 +205,7 @@ m = MelleaSession( ) ``` -See [Backends and Configuration](../guide/backends-and-configuration) for the +See [Backends and Configuration](../how-to/backends-and-configuration) for the full `OpenAIBackend` reference. ## Troubleshooting @@ -240,5 +240,5 @@ pip install mellea --- -**See also:** [Backends and Configuration](../guide/backends-and-configuration) | +**See also:** [Backends and Configuration](../how-to/backends-and-configuration) | [Getting Started](../getting-started/installation) diff --git a/docs/docs/integrations/openai.md b/docs/docs/integrations/openai.md index 74fa0518b..971c0615d 100644 --- a/docs/docs/integrations/openai.md +++ b/docs/docs/integrations/openai.md @@ -234,7 +234,7 @@ m = MelleaSession( > **Note (review needed):** Direct Anthropic API compatibility via this path has not > been verified against the current Mellea version. If you are using Anthropic, > LiteLLM provides a verified integration — see -> [Backends and Configuration](../guide/backends-and-configuration). +> [Backends and Configuration](../how-to/backends-and-configuration). ## Troubleshooting @@ -256,5 +256,5 @@ local servers, list available models from the server's API or UI. --- -**See also:** [Backends and Configuration](../guide/backends-and-configuration) | +**See also:** [Backends and Configuration](../how-to/backends-and-configuration) | [Enforce Structured Output](../how-to/enforce-structured-output) diff --git a/docs/docs/integrations/smolagents.md b/docs/docs/integrations/smolagents.md index ccbeefde4..fcf427fb9 100644 --- a/docs/docs/integrations/smolagents.md +++ b/docs/docs/integrations/smolagents.md @@ -55,11 +55,11 @@ description and parameter types are preserved exactly. | -------- | --- | | Your tool exists as a LangChain `BaseTool` | [`MelleaTool.from_langchain(tool)`](./langchain) | | Your tool exists as a smolagents `Tool` | `MelleaTool.from_smolagents(tool)` | -| You have a plain Python function to expose | [`@tool` decorator](../guide/tools-and-agents) | +| You have a plain Python function to expose | [`@tool` decorator](../how-to/tools-and-agents) | | You have LangChain message history to continue | [`convert_to_openai_messages` → `ChatContext`](./langchain.md#seeding-a-session-with-langchain-message-history) | | You want Mellea as an OpenAI endpoint for another framework | [`m serve`](./m-serve) | --- -**See also:** [Tools and Agents](../guide/tools-and-agents) | +**See also:** [Tools and Agents](../how-to/tools-and-agents) | [Context and Sessions](../concepts/context-and-sessions) diff --git a/docs/docs/integrations/vertex-ai.md b/docs/docs/integrations/vertex-ai.md index 59eccbd48..c49d0ff31 100644 --- a/docs/docs/integrations/vertex-ai.md +++ b/docs/docs/integrations/vertex-ai.md @@ -244,4 +244,4 @@ pip install google-cloud-aiplatform --- **See also:** [OpenAI and OpenAI-Compatible APIs](../integrations/openai) | -[Backends and Configuration](../guide/backends-and-configuration) +[Backends and Configuration](../how-to/backends-and-configuration) diff --git a/docs/docs/integrations/watsonx.md b/docs/docs/integrations/watsonx.md index 9356700ec..c59741f39 100644 --- a/docs/docs/integrations/watsonx.md +++ b/docs/docs/integrations/watsonx.md @@ -5,8 +5,8 @@ description: "Run Mellea with IBM WatsonX AI using the WatsonxAIBackend." --- > **Deprecated:** The native WatsonX backend is deprecated since v0.4. Use the -> [LiteLLM](../guide/backends-and-configuration#litellm-backend) or -> [OpenAI](../guide/backends-and-configuration#openai-backend) backend with a +> [LiteLLM](../how-to/backends-and-configuration#litellm-backend) or +> [OpenAI](../how-to/backends-and-configuration#openai-backend) backend with a > WatsonX-compatible endpoint instead. The WatsonX backend connects to IBM's managed AI platform. It requires an API key, @@ -111,4 +111,4 @@ pip install 'mellea[watsonx]' --- -**See also:** [Backends and Configuration](../guide/backends-and-configuration) +**See also:** [Backends and Configuration](../how-to/backends-and-configuration) diff --git a/docs/docs/tutorials/03-using-generative-stubs.md b/docs/docs/tutorials/03-using-generative-stubs.md index e53c73fda..3a9f635aa 100644 --- a/docs/docs/tutorials/03-using-generative-stubs.md +++ b/docs/docs/tutorials/03-using-generative-stubs.md @@ -258,4 +258,4 @@ context-steerable generative functions: --- -**See also:** [Generative Functions](../guide/generative-functions) | [The Requirements System](../concepts/requirements-system) | [Write Custom Verifiers](../how-to/write-custom-verifiers) +**See also:** [Generative Functions](../how-to/generative-functions) | [The Requirements System](../concepts/requirements-system) | [Write Custom Verifiers](../how-to/write-custom-verifiers) diff --git a/docs/docs/tutorials/04-making-agents-reliable.md b/docs/docs/tutorials/04-making-agents-reliable.md index a041f4e6f..a5b8bf2e7 100644 --- a/docs/docs/tutorials/04-making-agents-reliable.md +++ b/docs/docs/tutorials/04-making-agents-reliable.md @@ -489,4 +489,4 @@ agentic system: --- -**See also:** [The Requirements System](../concepts/requirements-system) | [Security and Taint Tracking](../advanced/security-and-taint-tracking) | [Tools and Agents](../guide/tools-and-agents) +**See also:** [The Requirements System](../concepts/requirements-system) | [Security and Taint Tracking](../advanced/security-and-taint-tracking) | [Tools and Agents](../how-to/tools-and-agents) diff --git a/docs/docs/tutorials/05-mifying-legacy-code.md b/docs/docs/tutorials/05-mifying-legacy-code.md index e4bcb119c..a9d4bde0a 100644 --- a/docs/docs/tutorials/05-mifying-legacy-code.md +++ b/docs/docs/tutorials/05-mifying-legacy-code.md @@ -194,5 +194,5 @@ modifying their class definitions: | `mify(obj)` | You don't own the class | **See also:** [MObjects and mify](../concepts/mobjects-and-mify) | -[Working with Data](../guide/working-with-data) | +[Working with Data](../how-to/working-with-data) | [Tutorial 03: Using Generative Stubs](./03-using-generative-stubs)