poietic-generator-api

1.0.02 versions

1.0.0latestOct 12, 2025
pre-cleanup-2026-06not indexedJun 9, 2026

github.com/OAuber/poietic-generator-llm-agents

AI-powered autonomous drawing agents for the Poietic Generator`

2 stars

0 dependents

License: not declared

Installation

# Add this to your shard.yml
dependencies:
  poietic-generator-api:
    github: OAuber/poietic-generator-llm-agents
    version: ~> 1.0.0

Then run:

shards install

shard.yml

No shard.yml has been indexed for 1.0.0. You can read it on the repository.

Dependencies

This version declares no dependencies.

README

🤖 Poietic Generator - LLM Agents

AI-powered autonomous drawing agents for the Poietic Generator

Part of the Poietic Generator ecosystem - A collaborative real-time drawing experiment since 1986.

🎯 Overview

This package provides autonomous AI agents that can participate in the Poietic Generator collaborative drawing experience. Each agent controls a 20×20 pixel cell and draws in real-time, creating emergent collective artworks.

What is Poietic Generator?

The Poietic Generator is a pioneering collaborative drawing system where multiple participants draw simultaneously on a shared grid. Each user sees their own 20×20 cell plus their neighbors' cells, creating a large evolving mosaic. This package extends this concept to AI agents, enabling human-AI co-creation.

Why LLM Agents?

🎨 Creative autonomy: Agents make artistic decisions based on spatial context
🤝 Collaboration: Agents detect and interact with neighboring cells (human or AI)
🧠 Emergent behavior: Complex patterns emerge from simple local rules
🔬 Experimentation: Study AI creativity, cooperation, and collective intelligence

✨ Features

Core Capabilities

✅ Multi-LLM Support: Anthropic Claude, OpenAI GPT, Ollama (local), Mistral
✅ Real-time Drawing: WebSocket-based live updates (20-25 pixels per iteration)
✅ Spatial Awareness: Agents analyze their 8 neighbors (N, S, E, W, NE, NW, SE, SW)
✅ Collaborative Strategies: Mirror, translation, rotation of neighbor patterns
✅ Artistic Techniques: 5 color palettes (monochromatic, complementary, triadic, analogous, warm→cold)
✅ Temporal Continuity: Agents remember and continue their previous drawings
✅ Graceful Fallback: Automatic recovery when LLM output fails

Advanced Features

🎨 Depth & Shadows: Color gradients for 3D effects
🔄 Progressive Drawing: Pixels sent gradually over iteration interval (smooth animation)
📊 Performance Analytics: Real-time monitoring (tokens/sec, response times)
🛡️ Robust Parsing: Handles malformed LLM outputs with compact text format
🌈 Palette Techniques: Contrast, harmony, atmospheric perspective
🧩 Border Prioritization: Enhanced collaboration at cell boundaries

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     Poietic Generator                           │
│                  (Crystal WebSocket Server)                     │
│                        Port 3001                                │
└────────────────────────────┬────────────────────────────────────┘
                             │
                ┌────────────┴────────────┐
                │                         │
       ┌────────▼────────┐       ┌───────▼────────┐
       │  Human Browser  │       │   AI Agent     │
       │   (Viewer)      │       │  (ai-player)   │
       └─────────────────┘       └────────┬───────┘
                                           │
                                  ┌────────▼────────┐
                                  │  AI Proxy Server│
                                  │   (FastAPI)     │
                                  │   Port 8003     │
                                  └────────┬────────┘
                                           │
                         ┌─────────────────┼─────────────────┐
                         │                 │                 │
                    ┌────▼─────┐   ┌──────▼──────┐   ┌──────▼──────┐
                    │ Anthropic│   │   OpenAI    │   │   Ollama    │
                    │  Claude  │   │     GPT     │   │   (Local)   │
                    └──────────┘   └─────────────┘   └─────────────┘

Components

public/ai-player.html: Web interface for launching AI agents
public/js/ai-player.js: Agent orchestration, WebSocket client, iteration loop
public/js/spatial-analysis.js: Neighbor detection and spatial context generation
public/js/llm-adapters/: LLM-specific prompt engineering and response parsing
python/poietic_ai_server.py: FastAPI proxy for LLM APIs (CORS, analytics, Ollama)
docs/MANUEL_*.md: Instruction manuals for each LLM (in French, used as system prompts)

🚀 Quick Start

Prerequisites

Poietic Generator server running (Crystal): Installation guide
Python 3.8+ (for AI proxy server)
Node.js / Web browser (for AI agent client)
API keys for external LLMs (Anthropic, OpenAI) OR Ollama for local inference

1. Start the Poietic Generator Server

cd poietic-generator-api
./bin/poietic-generator-api --port=3001

2. Start the AI Proxy Server

cd python
pip install -r requirements.txt
python poietic_ai_server.py
# Server running on http://localhost:8003

3. Launch AI Agents

Open http://localhost:3001/ai-player.html in your browser:

Select LLM: Choose Ollama (free, local) or Anthropic/OpenAI (requires API key)
Configure: Set iteration interval (default: 0s = immediate)
Customize (optional): Add a user prompt ("Draw abstract patterns", "Use only warm colors", etc.)
Start: Click "Start" → Agent connects and begins drawing

4. View the Collective Drawing

Open http://localhost:3001 in another browser tab to see humans and AI agents drawing together in real-time!

📦 Installation

Clone the Repository

git clone https://github.com/OAuber/poietic-generator-llm-agents.git
cd poietic-generator-llm-agents

Python Dependencies

cd python
pip install -r requirements.txt

Required packages:

fastapi (web framework)
uvicorn (ASGI server)
httpx (async HTTP client for Ollama)

Ollama (Optional, for Local Inference)

Install Ollama: https://ollama.ai/

# Pull the recommended model
ollama pull llama3.2:3b

# Or deploy on OVHcloud AI Deploy (GPU)
# See: https://www.ovhcloud.com/en/public-cloud/ai-deploy/

API Keys (Optional, for Cloud LLMs)

Anthropic: Get API key
OpenAI: Get API key

Store keys securely (.env file, environment variables, or enter directly in UI).

⚙️ Configuration

AI Proxy Server

Edit python/poietic_ai_server.py:

# Ollama endpoint (local or remote)
OLLAMA_URL = "http://localhost:11434"  # Local
# OLLAMA_URL = "https://your-ollama-instance.app.cloud.ovh.net"  # OVHcloud

# CORS origins (allow AI agent frontend)
origins = [
    "http://localhost:3000",
    "http://localhost:3001",
    "http://localhost:8080",
]

Agent Behavior

Edit public/js/llm-adapters/ollama.js (or anthropic.js):

// Number of pixels per iteration
maxTokens: 1000  // ~20-25 pixels for Ollama

// Ollama model
model: "llama3.2:3b"  // Lightweight, fast
// model: "llama3.1:8b"  // Better quality, slower

// Generation parameters
temperature: 0.7        // Creativity
repeat_penalty: 0.9     // Allow repetition for patterns

Instruction Manuals

Edit docs/MANUEL_OLLAMA.md to customize agent behavior:

## Section 4: FORMES À DESSINER

Tu peux dessiner :
- Geometric: circles, triangles, rectangles, spirals
- Letters/Symbols: A-Z, *, +, -, arrows
- Patterns: checkerboard, gradients, waves
- Organic: flowers, trees, fractals

📚 Usage

Basic Agent Launch

# 1. Start Poietic Generator
cd poietic-generator-api
./bin/poietic-generator-api --port=3001

# 2. Start AI proxy
cd python
python poietic_ai_server.py

# 3. Open browser
firefox http://localhost:3001/ai-player.html

Advanced: Multiple Agents

Open multiple tabs of ai-player.html to launch several agents simultaneously. Each agent gets a unique cell and can collaborate with neighbors!

Custom Prompts

Use the "Custom Prompt" field to guide agent behavior:

"Draw only geometric shapes"
"Use warm colors (red, orange, yellow)"
"Create a gradient from top to bottom"
"Collaborate with neighbors by extending their patterns"

Monitoring

Agent Console: View logs in browser DevTools (F12)
Analytics Dashboard: http://localhost:8003/analytics-dashboard.html
Ollama Stats: http://localhost:8003/ollama-stats.html

🤖 Supported LLM Providers

Provider	Model	Cost	Speed	Quality	Local
Ollama	`llama3.2:3b`	Free	⚡⚡⚡ Fast	⭐⭐⭐ Good	✅ Yes
Ollama	`llama3.1:8b`	Free	⚡⚡ Medium	⭐⭐⭐⭐ Very Good	✅ Yes
Anthropic	`claude-3-haiku`	$0.25/M tokens	⚡⚡⚡ Fast	⭐⭐⭐⭐ Very Good	❌ Cloud
Anthropic	`claude-3.5-sonnet`	$3/M tokens	⚡⚡ Medium	⭐⭐⭐⭐⭐ Excellent	❌ Cloud
OpenAI	`gpt-4o-mini`	$0.15/M tokens	⚡⚡⚡ Fast	⭐⭐⭐⭐ Very Good	❌ Cloud

Recommendation: Start with Ollama llama3.2:3b (free, fast, local). Upgrade to llama3.1:8b or Claude for better artistic quality.

🧠 How It Works

Agent Loop

1. Connect to Poietic Generator WebSocket
2. Receive initial state (my cell + neighbors)
3. LOOP every N seconds:
   a. Analyze spatial context (8 neighbors)
   b. Build prompt with:
      - My last strategy (continuity)
      - Neighbor updates (collaboration)
      - Color palette (artistic technique)
      - Custom user prompt
   c. Send prompt to LLM
   d. Parse response (strategy + pixels)
   e. Send pixels progressively to server
   f. Update neighbors' tracking
4. Repeat until stopped

Spatial Analysis

Each agent sees:

8 neighbors (N, S, E, W, NE, NW, SE, SW)
Recent updates (last 200 pixels per neighbor, ~8-10 iterations)
Border pixels (prioritized for collaboration)

Example prompt section:

Neighbors:
E (right, x=19) 🔗BORDER(3): 2,7:#E91E63 2,6:#1ABC9C 2,5:#1ABC9C
N (top, y=0) 🔗BORDER(12): 5,17:#964B00 7,17:#964B00 ...

Collaboration ideas (choose ONE or draw freely):
[1] 🔗 Mirror neighbor E: 19,7:#E91E63 19,6:#1ABC9C 19,5:#1ABC9C
[2] 🔗 Extend neighbor N: 5,0:#964B00 7,0:#964B00 9,0:#964B00

Compact Format

To minimize parsing errors, Ollama uses a compact text format instead of JSON:

strategy: yellow star with shadows
pixels: 10,5:#F1C40F 11,5:#F39C12 10,6:#D68910 11,6:#E67E22 ...

Benefits:

✅ Simpler for LLMs to generate
✅ Robust regex parsing
✅ Graceful fallback (generates random shapes if parsing fails)

Color Palettes

5 artistic techniques for depth and harmony:

Monochromatique (Monochromatic): 8 shades of one color (dark shadows → light highlights)
Complémentaires (Complementary): 2 opposite colors (strong contrast)
Triade (Triadic): 3 evenly-spaced colors (balanced harmony)
Analogues (Analogous): Adjacent colors (smooth transitions)
Chaud→Froid (Warm→Cold): Red/orange → blue/violet (atmospheric perspective)

Example:

Colors (Monochromatic): #3A2A1F #5C4A3F #7D6A5F #9D8A7F #BDA9A0 #DCC9C0 #F5E9E0 #FFF9F5
Use: dark for shadows/depth, light for highlights/foreground.

🎨 Advanced Features

Temporal Continuity

Agents remember their previous strategy and are encouraged to complete drawings:

Last iteration: "yellow star with shadows". CONTINUE it OR start new.

Result: Agents finish stars, letters, patterns instead of changing theme every iteration!

Border Collaboration

Agents prioritize pixels at common borders (x=0, x=19, y=0, y=19):

# Filter neighbor updates for border pixels
if direction == 'E':  # East neighbor
    border_pixels = updates.filter(u => u.x <= 2)  # Their left border
    # Transform to my right border (x=19)

Result: Seamless connections between cells (mirrored patterns, extended lines).

Progressive Drawing

Pixels are sent one-by-one over 80% of the iteration interval:

const delayBetweenPixels = (targetInterval * 0.8) / pixels.length;
for (const pixel of pixels) {
    sendPixel(pixel);
    await sleep(delayBetweenPixels);
}

Result: Smooth animation instead of sudden "flashes" every iteration.

Geometric Transformations

When neighbors draw at borders, agents receive transformation suggestions:

Mirror (horizontal/vertical)
Translation (shift pattern)
Rotation (90°)

Example:

[1] 🔗 Mirror neighbor W: 0,5:#E74C3C 1,5:#C85A3F 2,5:#AF7AC5
[2] 🔗 Translate neighbor N: 5,0:#964B00 7,0:#964B00 9,0:#964B00

📖 Documentation

docs/MANUEL_OLLAMA.md: Instructions for Ollama agents (French)
docs/MANUEL_ANTHROPIC.md: Instructions for Claude agents (French)
docs/MANUEL_OPENAI.md: Instructions for GPT agents (French)
docs/ARCHITECTURE.md: Technical architecture (coming soon)
docs/API.md: API reference (coming soon)

Architecture Diagrams

See docs/ARCHITECTURE_FORMATS_DONNEES.md for:

Data flow between components
JSON vs compact format usage
WebSocket message protocol

💡 Examples

Example 1: Monochromatique Agent

// Agent receives palette
Colors (Monochromatic): #3A2A1F #5C4A3F #7D6A5F #9D8A7F #BDA9A0 #DCC9C0
Use: dark for shadows/depth, light for highlights/foreground.

// Agent draws a sphere with shadows
strategy: sphere with shadows
pixels: 10,10:#3A2A1F 11,10:#5C4A3F 10,11:#7D6A5F 11,11:#9D8A7F ...

Visual: 🌑 A shaded ball (dark left/bottom, light right/top)

Example 2: Collaborative Border Extension

// Agent sees neighbor E drawing at border
E (right, x=19) 🔗BORDER(3): 2,7:#E91E63 2,6:#1ABC9C 2,5:#1ABC9C

// Collaboration suggestion
[1] 🔗 Mirror neighbor E: 19,7:#E91E63 19,6:#1ABC9C 19,5:#1ABC9C

// Agent chooses to collaborate
strategy: mirror [1]
pixels: 19,7:#E91E63 19,6:#1ABC9C 19,5:#1ABC9C 18,7:#C85A3F ...

Visual: Seamless color continuity across cell boundary!

Example 3: Temporal Continuity

// Iteration 1
strategy: yellow star
pixels: 10,8:#F1C40F 11,8:#F39C12 9,9:#E67E22 ...

// Iteration 2 (agent remembers)
Last iteration: "yellow star". CONTINUE it OR start new.
strategy: continue yellow star with highlights
pixels: 10,7:#F9E79F 11,7:#F8C471 9,10:#CA6F1E ...

// Result: A complete, finished star instead of abandoned fragments!

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-improvement
Commit your changes: git commit -m 'Add amazing improvement'
Push to the branch: git push origin feature/amazing-improvement
Open a Pull Request

Development Setup

# Clone your fork
git clone https://github.com/YOUR_USERNAME/poietic-generator-llm-agents.git
cd poietic-generator-llm-agents

# Install dependencies
cd python && pip install -r requirements.txt

# Run tests (coming soon)
# pytest tests/

Code Style

JavaScript: ES6+, 4-space indentation
Python: PEP 8, Black formatter
Documentation: English (code comments can be French)

📄 License

MIT License - see LICENSE file for details.

🙏 Credits

Original Concept

Olivier Auber - Creator of the Poietic Generator (1986-2025)
http://poietic-generator.net/

LLM Integration

Olivier Auber - Design & prompt engineering
Community contributors - Testing, feedback, improvements

Related Projects

Poietic Generator (Crystal/Crystal) - Main server
Poietic Generator History - Historical documentation

Acknowledgments

Anthropic, OpenAI, Meta (Llama) - LLM providers
OVHcloud - GPU infrastructure for Ollama deployment
Crystal community - WebSocket server framework
FastAPI community - Python proxy server

🔗 Links

Main Project: Poietic Generator
Live Demo: http://poietic-generator.net/ (coming soon)
Documentation: https://poietic-generator.github.io/poietic-generator-documentation/
Report Issues: GitHub Issues

Made with ❤️ for collective AI creativity 🎨🤖

"What emerges when (humans and) AI draw together?"