docs: updated agents.md and other smaller docs fixes

docs/agents.md

@@ -1,24 +1,34 @@
 # Agents
 
-Sharing tools and agents on the HF Hub in a standardized way is not implemented yet.
-This page contains some initial thoughts on this. 
+How could the sharing of agents be standardized on the HF Hub?
 
-## Main components of agents
-Agents have several main components:
+A good standard for sharing agents should be: modular, open, and interoperable. 
 
-- A glue library like [autogen](https://github.com/microsoft/autogen), [CrewAI](https://github.com/crewAIInc/crewAI), [langchain](https://github.com/langchain-ai/langchain), or [transformers.agents](https://huggingface.co/docs/transformers/en/agents), which orchestrate a series of LLM calls and tool use.
-- A set of prompt templates that define different tasks and agent personas.
-- A set of tools, either as JSON strings or Python functions.
-- A compute environment to run the agent code invoking the prompts and tools.
+## Modularity: Main components of agents
+Agents have four main components:
 
+1. An orchestration library such as [autogen](https://github.com/microsoft/autogen), [CrewAI](https://github.com/crewAIInc/crewAI), [langchain](https://github.com/langchain-ai/langchain), or [transformers.agents](https://huggingface.co/docs/transformers/en/agents), which implements prompt formatting, tool parsing, API calls, agent interaction etc.
+2. A set of prompt templates that define different tasks and agent personas.
+3. A set of tools, provided as JSON strings, Python dictionaries, or functions.
+4. A compute environment to run the agent code, invoking the prompts and tools.
 
-## Sharing agents on the HF Hub
+**Modularity** is a fundamental principle in software engineering. It enables maintainability, reusability, scalability, and testability. In practice, however, the code for LLM systems and agents often combines prompt strings, tool functions and the agent orchestration code in the same files. This means that changes in prompts are hard to test and version and it is harder for others to reuse prompt templates or tools for their own systems. 
 
-HF Space repos provide a suitable compute environment for agent code and Space repos can also host the YAML/JSON files for prompt templates and tools.
+Following the principle of modularity, agents should be shared in a directory of modular .yaml/.json files for prompt templates; .py files for tools; and a single agent.py file for the orchestration code. 
+
+
+## Openness: Sharing and running agents on the HF Hub
+
+HF Space repositories provide a suitable unit for storing the files for prompt templates, tools and orchestration code in a single directory, combined with attached compute for executing the agent. One Space can contain one agent, which can be executed on a free CPU, or with high-end GPUs if required. HF Spaces can be public, private or shared with a group of people in a specific organization.
 
 [TODO: add example of a HF Space repo with an agent.]
 
 
+## Interoperability
+
+Several different orchestration frameworks for agents exist. [TODO ...]
+
+
 <!-- 
 1. Example: Agent Model Repo
     - (maybe:) OAI MLEBench Agents/Dataset: https://github.com/openai/mle-bench (Seems like no nice tabular dataset provided.)

docs/index.md

@@ -1,27 +1,15 @@
 # Prompts on the Hugging Face Hub
 
-Prompts have become a key artifact for researchers and practitioners working with AI. 
-There is, however, no standardized way of sharing prompts.
-Prompts are shared on the HF Hub in [.txt files](https://huggingface.co/HuggingFaceFW/fineweb-edu-classifier/blob/main/utils/prompt.txt),
-in [HF datasets](https://huggingface.co/datasets/fka/awesome-chatgpt-prompts),
-as strings in [model cards](https://huggingface.co/OpenGVLab/InternVL2-8B#grounding-benchmarks),
-or on GitHub as [python strings](https://github.com/huggingface/cosmopedia/tree/main/prompts), 
-in [JSON, YAML](https://github.com/hwchase17/langchain-hub/blob/master/prompts/README.md),
-or in [Jinja2](https://github.com/argilla-io/distilabel/tree/main/src/distilabel/steps/tasks/templates). 
+Prompts have become key artifacts for researchers and practitioners working with AI. There is, however, no standardized way of sharing prompts. Prompts are shared on the HF Hub in [.txt files](https://huggingface.co/HuggingFaceFW/fineweb-edu-classifier/blob/main/utils/prompt.txt), in [HF datasets](https://huggingface.co/datasets/fka/awesome-chatgpt-prompts), as strings in [model cards](https://huggingface.co/OpenGVLab/InternVL2-8B#grounding-benchmarks), or on GitHub as [python strings](https://github.com/huggingface/cosmopedia/tree/main/prompts), in [JSON, YAML](https://github.com/hwchase17/langchain-hub/blob/master/prompts/README.md), or in [Jinja2](https://github.com/argilla-io/distilabel/tree/main/src/distilabel/steps/tasks/templates). 
 
 
 
 ## Objectives and non-objectives of this library
 ### Objectives
 1. Provide a Python library that simplifies and standardises the sharing of prompts on the Hugging Face Hub.
-2. Start an open discussion on the best way of standardizing and 
-encouraging the sharing of prompts on the HF Hub, building upon the HF Hub's existing repository types 
-and ensuring interoperability with other prompt-related libraries.
+2. Start an open discussion on the best way of standardizing and encouraging the sharing of prompts on the HF Hub, building upon the HF Hub's existing repository types and ensuring interoperability with other prompt-related libraries.
 ### Non-Objectives: 
-- Compete with full-featured prompting libraries like [LangChain](https://github.com/langchain-ai/langchain), 
-[ell](https://docs.ell.so/reference/index.html), etc. The objective is, instead, 
-a simple solution for sharing prompts on the HF Hub, which is compatible with 
-other libraries and which the community can build upon. 
+- Compete with full-featured prompting libraries like [LangChain](https://github.com/langchain-ai/langchain), [ell](https://docs.ell.so/reference/index.html), etc. The objective is, instead, a simple solution for sharing prompts on the HF Hub, which is compatible with other libraries and which the community can build upon. 
 
 
 ## Quick start

docs/repo_types_examples.md

@@ -7,12 +7,12 @@ The HF Hub is currently organized around three main repository types:
 - Dataset repositories: Repos with tabular datasets (mostly in parquet format). 
 - Spaces repositories: Repos with hosted applications (often with code and data, which is then visualized in the Space).
 
-Prompt templates can be integrated in any of these repository types as .yaml or .json files. [TODO: add JSON support, currently only YAML is supported.]
+Prompt templates can be integrated into any of these repository types as .yaml or .json files. [TODO: add JSON support, currently only YAML is supported.]
 
 
 
 ## 1. Prompt templates as independent artifacts in model repos
-Many prompt templates can be reused with many different models and are not linked to specific model weights. These prompt templates can be shared in a HF model repo, where the model card provides a description and usage instructions, and prompts are shared via .yaml or .json files in the same repository.
+Many prompt templates can be reused with various models and are not linked to specific model weights. These prompt templates can be shared in an HF model repo, where the model card provides a description and usage instructions, and prompts are shared via .yaml or .json files in the same repository.
 
 
 <details>
@@ -229,7 +229,7 @@ The prompts could be directly added to the dataset repository in the standardize
 
 ## 4. Attaching prompts to HF Spaces
 
-See also the [Agents](docs/agents.md) and [Tools](docs/tools.md) page for using HF Spaces for hosting prompts and tools as part of agents.
+See also the [Agents](agents.md) and [Tools](tools.md) page for using HF Spaces for hosting prompts and tools as part of agents.
 
 [TODO: create example]
 

docs/standard_prompt_format.md

@@ -1,11 +1,11 @@
 # Standardizing prompt templates
 
-The library expects prompts to be stored in YAML or JSON files in any HF Hub repository. See the `Files` tab in these repos for [open-weight model prompts](https://huggingface.co/MoritzLaurer/open_models_special_prompts), [closed-model prompts](https://huggingface.co/MoritzLaurer/closed_system_prompts), or [dataset prompts](https://huggingface.co/datasets/MoritzLaurer/dataset_prompts).
+The library expects prompts to be stored as YAML or JSON files in any HF Hub repository. See the `Files` tab in these repos for [open-weight model prompts](https://huggingface.co/MoritzLaurer/open_models_special_prompts), [closed-model prompts](https://huggingface.co/MoritzLaurer/closed_system_prompts), or [dataset prompts](https://huggingface.co/datasets/MoritzLaurer/dataset_prompts).
 
 The YAML files must follow the following structure:
 
 - Top-level key (required): `prompt`. 
-- Second-level key (required): *Either* `messages` *or* `template`. If `messages`, the prompt template must be provded as a list of dictionaries following the OpenAI messages format. This format is recommended for use with LLM APIs or inference containers.  If `template`, the prompt must be provided as a single string. 
+- Second-level key (required): *Either* `messages` *or* `template`. If `messages`, the prompt template must be provided as a list of dictionaries following the OpenAI messages format. This format is recommended for use with LLM APIs or inference containers.  If `template`, the prompt should be provided as a single string. 
 - Second-level keys (optional): (1) `input_variables`: an optional list of variables for populating the prompt template. This is also used for input validation; (2) `metadata`: Other information, such as the source, date, author etc.; (3) Any other key of relevance, such as `client_settings` with parameters for reproducibility with a specific inference client, or `metrics` form evaluations on specific datasets.
 
 This structure is inspired by the LangChain [PromptTemplate](https://python.langchain.com/api_reference/core/prompts/langchain_core.prompts.prompt.PromptTemplate.html) 

docs/tools.md

@@ -11,6 +11,7 @@ Different companies use slightly different language and implementations for this
 ## Main components of tools
 
 LLM tools have the following main components: 
+
 1. A textual description of the tool, including its inputs and outputs. This description is passed to the LLM's prompt, to enable it to produce text outputs that fit to the tool's description. For closed-source LLM, this integration of the tool description into the prompt is hidden. 
 2. Code that implements the tool. For example a simple Python function taking a search query text as input, does an API call, and returns ranked search results as output. 
 3. A compute environment in which the tool's code is executed. This can e.g. be your local computers' development environment, or docker container running on a cloud CPU. 
@@ -22,7 +23,7 @@ The tutorials of **LLM API providers** format tools either as Python dictionarie
 
 **LLM agent libraries** all have their own implementations of tools for their library: [LangChain Tools](https://github.com/langchain-ai/langchain/tree/master/libs/langchain/langchain/tools), LangChain Community [Tools](https://github.com/langchain-ai/langchain/tree/master/libs/community/langchain_community/tools) or [Agent Toolkits](https://github.com/langchain-ai/langchain/tree/a83357dc5ab5fcbed8c2dd7606e9ce763e48d194/libs/community/langchain_community/agent_toolkits) ([docs](https://python.langchain.com/docs/how_to/#tools)); [LlamaHub](https://llamahub.ai/?tab=tools) ([docs](https://docs.llamaindex.ai/en/stable/understanding/agent/tools/), [docs](https://docs.llamaindex.ai/en/stable/module_guides/deploying/agents/tools/)); [CrewAI Tools](https://github.com/crewAIInc/crewAI-tools) ([docs](https://docs.crewai.com/concepts/tools), including wrapper for using LangChain and LlamaHub tools); [AutoGen](https://github.com/microsoft/autogen/tree/main/python/packages/autogen-core/src/autogen_core/components/tools) ([docs](https://microsoft.github.io/autogen/dev//user-guide/core-user-guide/framework/tools.html), including a LangChain [tool wrapper](https://github.com/microsoft/autogen/tree/main/python/packages/autogen-ext/src/autogen_ext/tools)); [Transformers Agents](https://github.com/huggingface/transformers/tree/main/src/transformers/agents) etc.
 
-As all of these libraries and their tool collections are hosten on GitHub, this makes GitHub the main platform for sharing LLM tools today. 
+As all of these libraries and their tool collections are hosten on GitHub, GitHub has indirectly become the main platform for sharing LLM tools today, although it has not been designed for this purpose. 
 
 The main standardizing force for LLM tools are the API specifications and the expected JSON input format of LLM API providers. As OpenAI is the main standard setter, most libraries are compatible with the JSON input format specified in the OpenAI function/tool calling [guide](https://platform.openai.com/docs/guides/function-calling) and [docs](https://platform.openai.com/docs/api-reference/chat/create#chat-create-tools). In the field of agents, this has lead to the json agent paradigm. (Note that this requirement of LLM API compatibility is unnecessary in the code agent paradigm, where the LLM writes executable code itself, instead of only writing the structured input for existing code.)
 
@@ -39,8 +40,8 @@ Alternatively, tools could be shared as .json files, but this would decouple the
 
 ## Current implementation in transformers.agents
 
-`Transformers.Agents` currently has [Tool.push_to_hub](https://huggingface.co/docs/transformers/v4.45.2/en/main_classes/agent#transformers.Tool.push_to_hub) which pushes tools to the hub as a Space. Some tools & prompts have been stored like this [here](https://huggingface.co/huggingface-tools) on the Hub. This makes sense if users want a hosted tool with compute, but it is not interoperable with API client libraries. 
-[TODO: Think more about this]
+`transformers.agents` currently has [Tool.push_to_hub](https://huggingface.co/docs/transformers/v4.45.2/en/main_classes/agent#transformers.Tool.push_to_hub) which pushes tools to the hub as a Space. Some tools & prompts have been stored like this [here](https://huggingface.co/huggingface-tools) on the Hub. This makes sense if users want a hosted tool with compute. The modularity and interoperability of this approach, however, can probably be improved. Tools as single functions in .py files would be independent units that can be reuse more easily by others and would be more interoperable with other libraries. 
+