wip: adding agents

README.md

@@ -46,11 +46,22 @@ Tools to add:
  - build
    - docker
 
+### Environment
+
+The following variables can be set in the environment.
+
+| Name | Description | Default       |
+|-------|------------|---------------|
+| `FRACTALE_MCP_PORT` | Port to run MCP server on, if using http variant | 8089 |
+| `FRACTALE_MCP_TOKEN` | Token to use for testing | unset |
+| `FRACTALE_LLM_PROVIDER` | LLM Backend to use (gemini, openai, llama) | gemini |
+
 ### Testing
 
 Start the server in one terminal. Export `FRACTALE_MCP_TOKEN` if you want to require simple token auth. Here is for http.
 
 ```bash
+export FRACTALE_TOKEN_AUTH=dudewheresmycar
 fractale start --transport http --port 8089
 ```
 
@@ -64,26 +75,41 @@ curl -s http://0.0.0.0:8089/health  | jq
 python3 examples/mcp/test_echo.py
 ```
 
-TODO:
+### Agents
 
- - we will want to keep track of state (retries, etc.) for agents somewhere.
+The `fractale agent` command provides means to run build, job generation, and deployment agents.
+In our [first version](https://github.com/compspec/fractale), an agent corresponded to a kind of task (e.g., build). For this refactored version, the concept of an agent is represented in a prompt or persona, which can be deployed by a generic MCP agent with some model backend (e.g., Gemini, Llama, or OpenAI). Let's test
+doing a build:
 
-### Agents
+```bash
+# In both terminals
+export FRACTALE_MCP_TOKEN=dude
 
-**Not written yet**
+# In one terminal (start MCP)
+fractale start -t http --port 8089
 
-The `fractale agent` command provides means to run build, job generation, and deployment agents.
-This part of the library is under development. There are three kinds of agents:
+# Define the model (provider and endpoints) to use.
+export FRACTALE_LLM_PROVIDER=openai
+export OPENAI_API_KEY=xxxxxxxxxxxxxxxx
+export OPENAI_BASE_URL=https://my.custom.url/v1
+
+# In the other, run the plan
+fractale agent ./examples/plans/docker-build-lammps.yaml
+```
 
- - `step` agents are experts on doing specific tasks (do hold state)
  - `manager` agents know how to orchestrate step agents and choose between them (don't hold state, but could)
- - `helper` agents are used by step agents to do small tasks (e.g., suggest a fix for an error)
+ - `step` agents are experts on doing specific tasks. This originally was an agent with specific functions to do something (e.g., docker build) and now is a generic MCP agent with a prompt that gives it context and a goal.
 
-The design is simple in that each agent is responding to state of error vs. success. In the [first version]() of our library, agents formed a custom graph. In this variant, we refactor to use MCP server tools. In the case of a step agent, the return code determines to continue or try again. In the case of a helper, the input is typically an erroneous response (or something that needs changing) with respect to a goal. For a manager, we are making a choice based on a previous erroneous step.
+The initial design of `helper` agents from the first fractale is subsumed by the idea of an MCP function. A helper agent _is_ an MCP tool.
+
+The design is simple in that each agent is responding to state of error vs. success. In the [first version](https://github.com/compspec/fractale) of our library, agents formed a custom graph. In this variant, we refactor to use MCP server tools. It has the same top level design with a manager, but each step agent is like a small state machine governed by an LLM with access to MCP tools and resources.
 
 See [examples/agent](examples/agent) for an example, along with observations, research questions, ideas, and experiment brainstorming!
 
-TODO refactor examples.
+#### TODO
+
+- refactor examples
+- debug why the startup is so slow.
 
 ### Design Choices
 
@@ -96,6 +122,33 @@ Here are a few design choices (subject to change, of course). I am starting with
 - The backend of FastMCP is essentially starlette, so we define (and add) other routes to the server.
 
 
+### Job Specifications
+
+#### Simple
+
+We provide a simple translation layer between job specifications. We take the assumption that although each manager has many options, the actual options a user would use is a much smaller set, and it's relatively straight forward to translate (and have better accuracy).
+
+See [examples/transform](examples/transform) for an example.
+
+#### Complex
+
+We want to:
+
+1. Generate software graphs for some cluster (fluxion JGF) (this is done with [compspec](https://github.com/compspec/compspec)
+2. Register N clusters to a tool (should be written as a python module)
+3. Tool would have ability to select clusters from resources known, return
+4. Need graphical representation (json) of each cluster - this will be used with the LLM inference
+
+See [examples/fractale](examples/fractale) for a detailed walk-through of the above.
+
+For graph tool:
+
+```bash
+conda install -c conda-forge graph-tool
+```
+
+<!-- ⭐️ [Documentation](https://compspec.github.io/fractale) ⭐️ -->
+
 ## License
 
 HPCIC DevTools is distributed under the terms of the MIT license.

examples/plans/docker-build-lammps.yaml

@@ -0,0 +1,18 @@
+name: "LAMMPS Pipeline"
+plan:
+  # A step is a generation and validation step, where validation often interacts with
+  # the system
+  - name: "build"
+    # This is the main prompt that will ask for (and generate) the Dockerfile
+    prompt: "docker_build_persona"
+    # And this is how we validate to exit this step.
+    validate: "docker_build"
+    inputs:
+      application: "LAMMPS (Large-scale Atomic/Molecular Massively Parallel Simulator)"
+      container: "ghcr.io/converged-computing/fractale-mcp:lammps-cpu"
+      environment: "Ubuntu 24.04, CPU Only"
+
+#  - name: "deploy"
+#    prompt: "k8s-deploy-persona"
+#    inputs:
+#      replicas: 4