duckflow 0.1.0

🦆 Have your ducks in a row, and watch them go. A playful pipeline framework for chaining AI and logic tasks.

DuckFlow 🦆

Have your ducks in a row, and watch them go.
A playful pipeline framework for chaining AI and logic tasks, built around the metaphor of ducks and flocks.

---

🐥 Core Concepts

• Duck → A modular unit (task handler). Example: query DuckDuckGo, call OpenAI, format CSV.
• Flock → A pipeline definition, chaining ducks together into a workflow.
• Pond → Your environment/configuration where ducks swim (e.g. knowledge base files, .env).

---

🚀 Installation

git clone https://github.com/yourname/duckflow.git
cd duckflow
python -m venv venv
source venv/bin/activate
pip install -e .

Create a .env file with your keys:

OPENAI_API_KEY=sk-yourkeyhere

---

🦆 Example: Quack Test

A toy demo duck that simply quacks back your input.

duckflow quack_test "Hello DuckFlow"   --ducks-dir ./examples/ducks   --flock-file ./examples/flock.json

Output:

Running flock: quack_test
Duck quack (type=quack_node) produced output: Quack! You said: Hello DuckFlow
Final flock result: Quack! You said: Hello DuckFlow

---

🌊 Example: Duck Pond Research

A flock where one duck does research and another summarizes with OpenAI, augmented by a local knowledge base.

duckflow duckpond_summary "Why do ducks love ponds?"   --ducks-dir ./examples/ducks   --flock-file ./examples/flock.json

Possible output:

Running flock: duckpond_summary
Duck duckpond_researcher (type=duckduckgo_research) produced output: Related info: Ducks are aquatic birds...; Ponds support ecosystems...
Duck duckpond_summarizer (type=openai_chat) produced output:
- Ducks love ponds because they provide food, safety, and social space.
- Ponds support ecosystems that ducks thrive on.
- Ducklings learn foraging in ponds.
Final flock result: - Ducks love ponds because they provide food, safety, and social space. ...

---

📂 Project Structure

duckflow/            # Core library
  core/              # Runner, duck, flock, registry, settings
  handlers/          # Duck handler implementations
examples/            # Example ducks, flocks, and KBs

---

📜 License

MIT