Launch improvements

.gitignore

@@ -11,6 +11,7 @@ logs/
 
 # Local .ww Schemas at root
 *.ww
+hidden-*/
 
 # Local one-off testing scripts
 *ignore.py

README.md

@@ -6,93 +6,122 @@
 [![License](https://img.shields.io/github/license/willwoodward/woodwork-engine?label=License&logo=open-source-initiative)](https://github.com/willwoodward/woodwork-engine/blob/main/LICENSE)
 [![GitHub Stars](https://img.shields.io/github/stars/willwoodward/woodwork-engine?label=Stars&logo=github)](https://github.com/willwoodward/woodwork-engine/stargazers)
 
-Welcome to woodwork-engine, an AI Agent IaC tool that aims to make developing and deploying AI Agents easier.
+**Build AI agents with configuration, not code.**
 
-Through defining components in a configuration language, an LLM will decompose the task into actionable steps, which can be executed using the supplied tools. We use latest research to inform design decisions, and we implement this as most of the setup is copy/paste across projects. Through only focussing on the necessary components of a system, this package should make designing custom, vertical agents much easier.
+Woodwork Engine lets you define AI agents using a simple declarative language (`.ww` files). Declare what you want—components, connections, and behavior—and Woodwork handles the rest.
 
 ## Table of Contents
 
+- [Why Woodwork?](#why-woodwork)
 - [Features](#features)
-- [Installation](#installation)
-- [Usage](#usage)
+- [Quick Start](#quick-start)
+- [Documentation](#documentation)
 - [Examples](#examples)
 - [Contributing](#contributing)
 - [License](#license)
 
-## Features
+## Why Woodwork?
 
-- A custom config language, woodwork (.ww files), allowing agent components to be declared
-- Integrations and communication between components are handled
-- Additional customisation or extension can be provided by implementing some of our interfaces
+Building AI agents usually means:
+- Writing boilerplate code over and over
+- Managing complex integrations between LLMs, tools, and data sources
+- Maintaining brittle orchestration logic
 
-![Screenshot 2025-01-01 160031](https://github.com/user-attachments/assets/1a1c759e-aa5e-4499-902f-6d8abd23b3b8)
+Woodwork takes a different approach: **Infrastructure as Code for AI agents.**
 
-A [roadmap](https://github.com/willwoodward/woodwork-meta/blob/main/ROADMAP.md) is provided with details on future features.
+Instead of writing Python to wire everything together, you declare your agent in a `.ww` file:
 
-## Installation
+```ww
+my_agent = agent llm {
+    model: language_model
+    tools: [web_search, calculator]
+}
 
-1. **Run `pip install woodwork-engine`**: This gives access to the `woodwork` CLI tool, along with the ability to parse and deploy AI Agent components from .ww files
-2. **Install the Woodwork extension on VSCode if relevant**: This provides syntax highlighting and intellisense for code in .ww files
+input = input command_line {
+    to: my_agent
+}
+```
 
-## Usage
+That's it. Woodwork handles orchestration, tool calling, memory, and communication.
 
-1. Begin by duplicating the [`.env.example`](./woodwork/config/) file and placing it in your project's root directory
-1. Rename the file to `.env` (ensure this is part of your project's `.gitignore` so that it isn't committed)
-1. Depending on the `.ww` configuration file, populate the `.env` file with your corresponding keys
+![Screenshot 2025-01-01 160031](https://github.com/user-attachments/assets/1a1c759e-aa5e-4499-902f-6d8abd23b3b8)
 
-See the `.env.example` file for further details.
+## Features
 
-Once you've configured your `.ww` config file and your `.env` file, there are two ways to run `woodwork`: A standalone application, or used as a dependency.
+**Declarative Configuration**
+- Define agents in simple `.ww` files instead of writing Python
+- Components are modular and reusable
+- Environment variables for secrets (`$OPENAI_API_KEY`)
 
-### Standalone Application
+**Powerful Control Flow**
+- **Hooks**: Listen to events for logging and monitoring
+- **Pipes**: Transform data as it flows between components
+- **Routing**: Declarative message passing between components
 
-1. **Create a main.ww file and write some code**: This file is where component declarations are read from. For some inspiration, consult the examples
-1. **Run `woodwork init`**: This installs the necessary dependencies to run your components
-1. **Run `woodwork`**: This activates the components and initializes a logger
+**Rich Integrations**
+- LLMs: OpenAI, Ollama, HuggingFace
+- Knowledge: Vector databases (Chroma), graph databases (Neo4j), text files
+- Tools: Function calling, web APIs, command-line tools
+- I/O: CLI, voice input/output, streaming
 
-### As A Dependency
+## Quick Start
 
-When using `woodwork` as a dependency, you will need to build your own logger implementation. Not building your own logger will result in no logs being generated but the application will still run.
+```bash
+# Install
+pip install woodwork-engine
 
-1. (Optional) **Create a `./config` directory**: This is where the logging configuration will live.
-1. (Optional) **Copy the [`log_config.json`](./woodwork/config/log_config.json) into your `./config` directory**: This configures your logger
-1. In your file you'd like to utilize `woodwork` in, add `from woodwork import __main__ as m`
-1. See [`dev-main.py`](./dev-main.py) for how to build your logger and configure calling `woodwork`
+# Create a simple agent configuration
+cat > main.ww << 'EOF'
+my_llm = llm openai {
+  model: "gpt-4o-mini"
+  api_key: $OPENAI_API_KEY
+}
 
-## Developer Setup
+input = input command_line {
+  to: my_llm
+}
+EOF
 
-If you are interested in contributing, the following steps are used to activate a developer environment.
+# Set up your API key
+echo "OPENAI_API_KEY=your-key-here" > .env
 
-1. Install `pre-commit` if needed via `pip install pre-commit`
-1. Run `pre-commit install [--hook-type pre-push]` to run linting and formatting before commiting or pushing
+# Install dependencies and run
+woodwork --init
+woodwork
+```
 
-## Available Arguments
+That's it! You now have a running AI agent.
 
-You can pass arguments to `woodwork`. For more details, see `woodwork --help`.
+## Documentation
 
-|Argument|Options|Default|Notes|
-|-|-|-|-|
-|`--mode`|`run`, `debug`, `embed`, `clear`|`run`|Debug is deprecated, use Run instead. If using a workflow, you must use `embed` or `clear`.|
-|`--init`|`none`, `isolated`, `all`|`none`||
-|`--workflow`|`none`, `add`, `remove`, `find`|`none`|If specifying a workflow, you must provide a target.|
-|`--target`|String|`""`|Defines the target for the workflow. For add workflows, specify the file path to the workflow. For `remove` workflows, specify the workflow ID. For `find` workflows, specify the search query.|
-|`--version`|N/A|N/A|Prints the current version of Woodwork. Note: this will override any other arguments.|
+- **[Quickstart Guide](docs/quickstart.md)** - Get up and running in 5 minutes
+- **[Beginner Overview](docs/beginner-overview.md)** - Understand the core concepts
+- **[Philosophy](docs/explanation/philosophy.md)** - Why Infrastructure as Code for agents?
+- **[Control Flow](docs/explanation/control-flow.md)** - Master hooks, pipes, and events
+- **[Glossary](docs/glossary.md)** - Common terms and definitions
 
-When calling your script, you can pass argument to the script as long as they do not conflict with `woodworks` arguments.
+## Examples
 
-## Logging
+Check out the `examples/` directory for ready-to-run configurations:
 
-In `log_config.json`, you can set the desired logging levels for stdout and the generated log file. Do this by editing the respective `level` property in the json for the respective handler. Options include the standard logging levels: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.
+- **`01-short-term-memory-agent/`** - Agent with conversational memory
+- **`02-function-tooling-agent/`** - Agent that can call custom functions
+- **`04-plan-caching-agent/`** - Agent with workflow caching for repeated tasks
+- **`message-bus-demo/`** - Advanced routing with hooks and pipes
 
-You can monitor the log file during execution by opening a terminal and entering `tail -f logs/debug_log.log` (or your custom log file name if modified in the `log_config.json`)
+Each example includes a `main.ww` file and any required Python scripts. Just add your API keys to a `.env` file and run!
 
-## Examples
+## Contributing
 
-For some examples, consult the examples folder. ENV variables are denotes by a '$', place a .env file in the same directory as the main.ww file and populate it with the necessary variables.
+We'd love your help! Check out:
 
-## Contributing
+- **[CONTRIBUTING.md](https://github.com/willwoodward/woodwork-meta/blob/main/CONTRIBUTING.md)** - Contribution guidelines
+- **[woodwork-language](https://github.com/willwoodward/woodwork-language)** - VSCode extension for `.ww` syntax highlighting
+- **[woodwork-website](https://github.com/willwoodward/woodwork-website)** - Documentation website
+
+## Roadmap
 
-To view the contributing guide for woodwork, the [CONTRIBUTING.md](https://github.com/willwoodward/woodwork-meta/blob/main/CONTRIBUTING.md) file in the meta repository contains more information. We would love your help! Additionally, if you prefer working on other projects aligned with language servers or web development, [woodwork-language](https://github.com/willwoodward/woodwork-language) and [woodwork-website](https://github.com/willwoodward/woodwork-website) could be worth taking a look at.
+See the [roadmap](https://github.com/willwoodward/woodwork-meta/blob/main/ROADMAP.md) for planned features and improvements.
 
 ## License