feat: implement step tracking and event streaming

README.md

@@ -1,81 +1,119 @@
-<br />
+# Codegen API Server
 
-<p align="center">
-  <a href="https://docs.codegen.com">
-    <img src="https://i.imgur.com/6RF9W0z.jpeg" />
-  </a>
-</p>
+A FastAPI server that provides a streaming interface to the Codegen SDK.
 
-<h2 align="center">
-  The SWE that Never Sleeps
-</h2>
+## Features
 
-<div align="center">
+- Run Codegen agents with real-time status updates
+- Server-Sent Events (SSE) for live task progress
+- Step-by-step progress tracking
+- Configurable timeouts (default 30 minutes)
+- Heartbeat events to maintain connections
 
-[![PyPI](https://img.shields.io/badge/PyPi-codegen-gray?style=flat-square&color=blue)](https://pypi.org/project/codegen/)
-[![Documentation](https://img.shields.io/badge/Docs-docs.codegen.com-purple?style=flat-square)](https://docs.codegen.com)
-[![Slack Community](https://img.shields.io/badge/Slack-Join-4A154B?logo=slack&style=flat-square)](https://community.codegen.com)
-[![License](https://img.shields.io/badge/Code%20License-Apache%202.0-gray?&color=gray)](https://github.com/codegen-sh/codegen-sdk/tree/develop?tab=Apache-2.0-1-ov-file)
-[![Follow on X](https://img.shields.io/twitter/follow/codegen?style=social)](https://x.com/codegen)
+## Installation
 
-</div>
+```bash
+pip install -r requirements.txt
+```
 
-<br />
+## Environment Variables
 
-The Codegen SDK provides a programmatic interface to code agents provided by [Codegen](https://codegen.com).
+- `CODEGEN_ORG_ID`: Your Codegen organization ID
+- `CODEGEN_TOKEN`: Your Codegen API token
+- `SERVER_PORT`: Port to run the server on (default: 8000)
 
-```python
-from codegen.agents.agent import Agent
+## Usage
 
-# Initialize the Agent with your organization ID and API token
-agent = Agent(
-    org_id="YOUR_ORG_ID",  # Find this at codegen.com/developer
-    token="YOUR_API_TOKEN",  # Get this from codegen.com/developer
-    # base_url="https://codegen-sh-rest-api.modal.run",  # Optional - defaults to production
-)
+Start the server:
 
-# Run an agent with a prompt
-task = agent.run(prompt="Implement a new feature to sort users by last login.")
+```bash
+python backend/api.py
+```
 
-# Check the initial status
-print(task.status)
+### API Endpoints
 
-# Refresh the task to get updated status (tasks can take time)
-task.refresh()
+#### Run an Agent
 
-# Check the updated status
-print(task.status)
+```http
+POST /run
+Content-Type: application/json
 
-# Once task is complete, you can access the result
-if task.status == "completed":
-    print(task.result)  # Result often contains code, summaries, or links
+{
+    "prompt": "Your prompt here",
+    "thread_id": "optional_thread_id"
+}
 ```
 
-## Installation and Usage
+Response:
+```json
+{
+    "task_id": "task_123",
+    "thread_id": "thread_456"
+}
+```
 
-Install the SDK using pip or uv:
+#### Get Task Status
 
-```bash
-pip install codegen
-# or
-uv pip install codegen
+```http
+GET /status/{task_id}
 ```
 
-Get started at [codegen.com](https://codegen.com) and get your API token at [codegen.com/developer](https://codegen.com/developer).
+Response:
+```json
+{
+    "status": "in_progress",
+    "result": null,
+    "error": null
+}
+```
+
+#### Stream Task Events
 
-You can interact with your AI engineer via API, or chat with it in Slack, Linear, Github, or on our website.
+```http
+GET /events/{task_id}
+```
+
+Response (Server-Sent Events):
+```
+data: {"status": "in_progress", "task_id": "123", "current_step": "Analyzing code", "step_number": 1}
 
-## Resources
+data: {"status": "completed", "task_id": "123", "result": "Success"}
 
-- [Docs](https://docs.codegen.com)
-- [Getting Started](https://docs.codegen.com/introduction/getting-started)
-- [Contributing](CONTRIBUTING.md)
-- [Contact Us](https://codegen.com/contact)
+data: [DONE]
+```
+
+## Development
+
+Run tests:
+
+```bash
+pytest tests/
+```
+
+## Event Format
+
+Events are sent in Server-Sent Events (SSE) format with the following structure:
+
+```json
+{
+    "status": "in_progress",
+    "task_id": "123",
+    "timestamp": "2025-06-12T14:58:40Z",
+    "current_step": "Analyzing repository structure",
+    "step_number": 1
+}
+```
 
-## Contributing
+Status values:
+- `queued`: Task is queued
+- `in_progress`: Task is running
+- `completed`: Task completed successfully
+- `failed`: Task failed with error
+- `error`: Internal server error
 
-Please see our [Contributing Guide](CONTRIBUTING.md) for instructions on how to set up the development environment and submit contributions.
+## Timeouts and Heartbeats
 
-## Enterprise
+- Tasks timeout after 30 minutes (configurable via `max_retries`)
+- Heartbeat events sent every 5 seconds to keep connections alive
+- Failed tasks automatically cleaned up
 
-For more information on enterprise engagements, please [contact us](https://codegen.com/contact) or [request a demo](https://codegen.com/request-demo).