adalflow

Files (43)

• SKILL.md
• package-overview.md · references/
• repo-provenance.md · references/
• repo-routing-metadata.json · references/
• troubleshooting.md · references/
• check_adalflow_environment.py · scripts/
• SKILL.md · sub-skills/agents-tools-and-streaming/
• agents-and-tools.md · sub-skills/agents-tools-and-streaming/references/
• mcp-and-permissions.md · sub-skills/agents-tools-and-streaming/references/
• streaming-and-run-results.md · sub-skills/agents-tools-and-streaming/references/
• troubleshooting.md · sub-skills/agents-tools-and-streaming/references/
• agent_runner_fake_planner_smoke.py · sub-skills/agents-tools-and-streaming/scripts/
• function_tool_smoke.py · sub-skills/agents-tools-and-streaming/scripts/
• SKILL.md · sub-skills/core-components-and-structured-io/
• core-api-reference.md · sub-skills/core-components-and-structured-io/references/
• structured-io-and-parsers.md · sub-skills/core-components-and-structured-io/references/
• troubleshooting.md · sub-skills/core-components-and-structured-io/references/
• core_component_smoke.py · sub-skills/core-components-and-structured-io/scripts/
• structured_io_smoke.py · sub-skills/core-components-and-structured-io/scripts/
• SKILL.md · sub-skills/evaluation-and-optimization/
• datasets-and-benchmarks.md · sub-skills/evaluation-and-optimization/references/
• evaluation-metrics.md · sub-skills/evaluation-and-optimization/references/
• optimization-and-training.md · sub-skills/evaluation-and-optimization/references/
• troubleshooting.md · sub-skills/evaluation-and-optimization/references/
• evaluation_metrics_smoke.py · sub-skills/evaluation-and-optimization/scripts/
• SKILL.md · sub-skills/model-client-and-generator-workflows/
• api-reference.md · sub-skills/model-client-and-generator-workflows/references/
• generator-workflows.md · sub-skills/model-client-and-generator-workflows/references/
• model-clients.md · sub-skills/model-client-and-generator-workflows/references/
• troubleshooting.md · sub-skills/model-client-and-generator-workflows/references/
• generator_fake_client_smoke.py · sub-skills/model-client-and-generator-workflows/scripts/
• SKILL.md · sub-skills/retrieval-rag-and-data-pipelines/
• data-pipelines.md · sub-skills/retrieval-rag-and-data-pipelines/references/
• rag-recipes.md · sub-skills/retrieval-rag-and-data-pipelines/references/
• retrievers.md · sub-skills/retrieval-rag-and-data-pipelines/references/
• troubleshooting.md · sub-skills/retrieval-rag-and-data-pipelines/references/
• localdb_smoke.py · sub-skills/retrieval-rag-and-data-pipelines/scripts/
• text_splitter_smoke.py · sub-skills/retrieval-rag-and-data-pipelines/scripts/
• SKILL.md · sub-skills/tracing-observability-and-configuration/
• api-reference.md · sub-skills/tracing-observability-and-configuration/references/
• tracing-and-config.md · sub-skills/tracing-observability-and-configuration/references/
• troubleshooting.md · sub-skills/tracing-observability-and-configuration/references/
• tracing_smoke.py · sub-skills/tracing-observability-and-configuration/scripts/

SKILL.md (first lines)

# AdalFlow Repo Skill

Use this skill when a task involves the AdalFlow Python package: building model-agnostic LLM task pipelines, structured outputs, RAG, agents, tool calling, evaluation, prompt/few-shot/text-gradient optimization, or tracing.

AdalFlow uses PyTorch-like `Component` building blocks. A typical workflow combines `Prompt`, `ModelClient`, `Generator`, `DataClass`/parser objects, retrievers, tools, agents, metrics, and tracing callbacks.

## First checks

1. Read [repository provenance](references/repo-provenance.md) before assuming this skill is current for a checkout.
2. For a package install/import task, read [package overview](references/package-overview.md) and [root troubleshooting](references/troubleshooting.md).
3. For a quick environment smoke, run [check_adalflow_environment.py](scripts/check_adalflow_environment.py) in the target Python environment.
4. Then route to the most specific sub-skill below.

## Install/import guidance

For AdalFlow 1.1.1, use Python 3.9+ and include the OpenAI SDK for reliable top-level import because the current `Generator` module imports OpenAI response event types:

```bash
python -m pip install "adalflow[openai]"
python - <<'PY'
import adalflow as adal
print(adal.__version__)
from adalflow import Component, DataClass, Generator, Agent, Runner
print("adalflow import ok")
PY
```

Install additional extras only for workflows that need them, such as provider SDKs, FAISS/LanceDB/Postgres/Qdrant retrieval, MCP, torch/transformers, datasets, or SQLAlchemy. Do not treat a missing API key, service, dataset, or accelerator as a base package failure.

## Route map

### Core components and structured I/O

Read [core-components-and-structured-io](sub-skills/core-components-and-structured-io/SKILL.md) for:

- `Component`, `DataComponent`, `Sequential`, `ComponentList`, `Prompt`, `DataClass`, and `required_field`.
- JSON/YAML/list/int/float/bool parsers and `DataClassParser` structured-output prompts.
- Service-free mini-pipeline checks that do not call a model provider.

### Model clients, generators, and embedders

Read [model-client-and-generator-workflows](sub-skills/model-client-and-generator-workflows/SKILL.md) for:

- `ModelClient`, `Generator`, `GeneratorOutput`, `Embedder`, and `BatchEmbedder`.
- `prompt_kwargs`, `model_kwargs`, `ModelType`, output processors, cache behavior, and async/streaming basics.
- Provider extras and no-credential fake-client tests.

### Retrieval, RAG, and data pipelines

Read [retrieval-rag-and-data-pipelines](sub-skills/retrieval-rag-and-data-pipelines/SKILL.md) for:

- `Document`, `TextSplitter`, `LocalDB`, `ToEmbeddings`, and `RetrieverOutputToContextStr`.
- `BM25Retriever`, `FAISSRetriever`, LanceDB, Postgres, Qdrant, and RAG context assembly.
- Optional vector-store, embedding-dimension, stale-index, and service troubleshooting.

### Agents, tools, streaming, HITL, and MCP

Read [agents-tools-and-streaming](sub-skills/agents-tools-and-streaming/SKILL.md) for:

- `FunctionTool`, `ToolManager`, `FunctionDefinition`, `FunctionOutput`, and `ToolOutput`.
- `Agent`, `Runner`, `ReActAgent`, `RunnerResult`, `StepOutput`, and stream events.
- Human approval/permission handlers, safe tool patterns, and optional MCP tools.

### Evaluation and optimization

Read [evaluation-and-optimization](sub-skills/evaluation-and-optimization/SKILL.md) for:

- `AnswerMatchAcc`, `RetrieverEvaluator`, cautious `LLMasJudge`, and dataset loaders.
- `Parameter`, `GradComponent`, `AdalComponent`, `Trainer`, `BootstrapFewShot`, `TGDOptimizer`, `EvalFnToTextLoss`, `LLMAsTextLoss`, and `optimize_anything`.
- Training/benchmark workflows that require provider credentials, data, and runtime budget.

### Tracing, observability, and configuration

Read [tracing-observability-and-configuration](sub-skills/tracing-observability-and-configuration/SKILL.md) for:

- `setup_env`, logging helpers, config loading, and default artifact roots.
- `GeneratorStateLogger`, `GeneratorCallLogger`, callbacks, spans, trace providers, and optional MLflow.
- Debug artifacts, path hygiene, and trace/log troubleshooting.

## Cross-workflow rules

- Start service-free when possible: validate `DataClass`, parser, `TextSplitter`, metrics, fake `ModelClient`, or fake `Runner` behavior before adding providers.
- Choose provider extras only after the required `ModelClient` is known. API credentials and network calls are workflow prerequisites, not skill smoke checks.
- For RAG, separate data preparation, retrieval index construction, context formatting, generator configuration, evaluation metrics, and tracing; each has a different owner sub-skill.
- For agents, verify tools independently with `FunctionTool`/`ToolManager` before letting an LLM planner call them.
- For optimization, define evaluation and loss contracts before running `Trainer.fit`; prefer `Trainer.diagnose` or metric smokes before expensive training.
- For tracing/logging, keep artifacts in explicit writable directories and avoid logging secrets, provider payloads, or machine-specific paths.

## When not to use this skill

- The task is only about editing this repository's release process, CI, or publishing scripts.
- The task needs a different package's APIs and only mentions AdalFlow as background context.
- The user asks Creator to perform downstream research directly; switch to Researcher mode instead of using this operating graph here.

From VectorSpaceLab/AREX-Skill, MIT.

More from VectorSpaceLab/AREX-Skill