Convo

Convo combines the power of AI, Speech Recognition & Machine Learning to provide you the conversational experience with AI through speech! Simply choose a language you'd like to speak in & start the convo!

---

Why Convo?

Asking an LLM to "create a snake game in Python" often yields a snake game, but with unpredictable features, styling, and structure. With Convo you get two clear steps:

1. Describe in Convo — Get a natural-language .convo program that defines behavior, layout, and style.
2. Generate code — Refine the Convo program until it matches what you want, then ask the model to implement it in your chosen language.

The resulting code is much closer to your specified behavior and design because the Convo program acts as a stable, editable specification.

---

Features

• Natural language syntax — Variables, control flow, functions, and UI described in everyday language.
• LLM-friendly — Designed for both generation and interpretation by LLMs.
• Target-agnostic — One Convo program can be ported to multiple languages (JS, Python, C#, Rust, etc.).
• Structured specs — Sections, modules, styles, and resources keep programs organized.
• Rich examples — Games (Snake, Tetris, Tron), tools (chart maker, invoice builder), agents, and CLI apps.

---

Project structure

convo/
├── convo-spec.md          # Full language specification
├── gpt-instructions.md    # Condensed Convo syntax for LLM prompts
├── README.md              # This file
├── LICENSE                # CC0 1.0 (Public Domain)
│
├── examples/              # Sample Convo applications
│   ├── snake.convo        # Snake game (→ .html, .py)
│   ├── tetris.convo       # Tetris (→ .html, .py)
│   ├── chart-maker.convo  # CSV → bar chart (→ .html)
│   ├── tron.convo         # Tron-style game (→ .html)
│   ├── invoice-builder.convo
│   ├── tweet-optimizer.convo
│   ├── components.convo   # UI components demo
│   ├── agent-booking.convo
│   └── fauxberry-cli/     # CLI example (Convo → Node.js)
│
├── agents/                # Multi-agent framework (Convo → JS/Python/C#)
│   ├── AgentServer/       # AgentServer.convo → AgentServer.js, .py, .cs
│   ├── DirectoryAgent/
│   ├── agent-client.convo # Test client UI (→ .html)
│   └── agent-server.js    # Sample server
│
├── realtime/              # Same spec, multiple languages
│   ├── realtime.convo     # OpenAI Realtime API client spec
│   ├── realtime.js        # Node.js
│   ├── realtime.py        # Python
│   ├── realtime.cs        # C#
│   └── realtime.rs        # Rust
│
├── sections/              # Reusable Convo sections & docs
│   ├── communication.md  # Message types for agents
│   ├── layouts.md
│   └── openai.md         # OpenAI API integration patterns
│
└── images/                # Screenshots and assets for documentation

---

Workflow

1. Create a new app (English → Convo)

Prompt your LLM with an idea; it generates a .convo file. Iterate on the Convo program (features, layout, styles) in natural language. No code yet.

2. Implement in a target language (Convo → Code)

When the Convo program is ready, ask the model to implement it in a specific language (e.g. "Implement this in Python" or "Port to JavaScript"). Reference convo-spec.md or gpt-instructions.md so the model follows Convo semantics.

3. Porting with prompt files

This repo uses .prompt files to capture implementation instructions. For example:

• AgentServer/AgentServer.convo — Module spec (classes, types, methods).
• AgentServer/AgentServer.js.prompt — "Implement the AgentServer module below for Node.js using express.js. Default port 4242."
• AgentServer/AgentServer.js — Generated JavaScript implementation.

The same .convo file can have .py.prompt, .cs.prompt, etc., to produce Python, C#, or other targets.

---

Convo at a glance

Convo uses natural language for variables, control flow, and structure:

Variables & assignment

Set the user's name to "Alice".
Let the final score be the average of all scores.

Conditionals & loops

If the user's age is 18 or more, then grant access.
For each item in the shopping cart, apply the discount.
While the user is not logged in, prompt for credentials.

Functions

To calculate the area of a circle, multiply pi by the radius squared.
Calculate the area of the circle.

Sections & UI

Section: Game Setup
Create a grid with 20 rows and 20 columns.
Create a snake starting at the center of the grid with a length of 3.

Section: Styles
Define a style called "Header" with font size 24, color blue, and bold.
Apply the "Header" style to the title.

Error handling

Attempt to read the uploaded file. If that fails, display "Please upload a valid CSV file."

For the complete grammar (operators, data structures, OOP, styles, resources, etc.), see convo-spec.md. For a compact reference suitable for LLM prompts, see gpt-instructions.md.

---

Examples

Example	Description	Outputs
Snake	Classic snake game	.html, .py
Tetris	Tetris with tetrominoes & scoring	.html, .py
Tron	Tron-style light-cycle game	.html
Chart maker	Upload CSV → bar chart	.html
Invoice builder	Build invoices from inputs	.html
Tweet optimizer	Optimize tweet text	.html
Agent client	Web UI to test AgentServer over WS	.html
AgentServer	Multi-agent server (tasks, handoffs)	.js, .py, .cs
Realtime	OpenAI Realtime API client	.js, .py, .cs, .rs
fauxberry-cli	CLI with “fauxberry” thinking loop	Node.js app

Open any .convo file in examples/ or agents/ to see the pattern; matching .html, .py, or .js files show one possible implementation.

---

Running the examples

• Web examples — Open the corresponding .html file in examples/ (e.g. examples/snake.html) in a browser. Some assume a local server or API keys; check comments in the file.
• Agents — From agents/: npm install then run agent-server.js (or the generated server). Use agent-client.html to connect and send TaskRequests.
• fauxberry-cli — See examples/fauxberry-cli/README.md for install and usage (requires Anthropic API key).

---

Reusable sections

The sections/ folder contains Convo snippets you can include in your programs:

• communication.md — Message types for multi-agent systems (TaskRequest, TaskResponse, HandoffNotification, etc.).
• layouts.md — Layout and structure patterns.
• openai.md — Patterns for calling OpenAI models (API key, model choice, chat completions).

Use these as reference or paste into prompts when generating Convo that integrates with agents or OpenAI.

---

License

This project is in the public domain under the CC0 1.0 Universal license. You can copy, modify, and distribute it without permission.

---

Contributing

Contributions are welcome. When adding or changing Convo programs:

• Keep convo-spec.md and gpt-instructions.md in sync with new language features.
• Use clear section names and natural language consistent with the spec.
• When contributing implementations from Convo, note the target language and any .prompt used.

If you use Convo in your own projects or with different LLMs, consider sharing your .convo examples or workflow tips.