WorldForgeAPI

KO | EN

gitlite — search

#javascript #python #react #typescript #go #golang #android #machine-learning #rust #macos #java #windows #awesome-list #openai

(★ 13)

Backend API system that uses AI agents to generate structured fantasy world data, propose events, validate updates, and manage world state with snapshot/versioning.

WorldForgeAPI Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# World Generation API - Test Phase

## Response to Your Questions

### 1. Timeline for Test Phase

**Estimated Duration: 2-3 days**

Breakdown:
- **Day 1**: Core structure, base schemas, and AI agents implementation
- **Day 2**: NarrativeController, API endpoints, snapshot system, and integration testing
- **Day 3**: Documentation, refinement, and final testing

This timeline ensures quality code, proper testing, and complete documentation.

### 2. Tools & Technology Stack

**Primary Stack:**
- **Python 3.9+** with **FastAPI** - Modern, fast web framework with automatic API documentation
- **SQLite** with async SQLAlchemy - Simple database for test phase (easily upgradable to PostgreSQL)
- **OpenAI API** (GPT-4o-mini) - Cost-effective AI generation with structured JSON responses
- **Pydantic** - Data validation and serialization
- **Uvicorn** - ASGI server for FastAPI

**Why this stack:**
- FastAPI provides excellent async performance and automatic OpenAPI documentation
- SQLite requires zero setup, perfect for test phase evaluation
- OpenAI integration is straightforward with good error handling and fallback logic
- Clean separation of concerns makes the codebase maintainable and extensible

### 3. Project Folder Structure (Short Overview)

```
app/
├── agents/          # AI Agent Layer (WorldDesigner, ContentBuilder, EventsAgent)
├── controllers/     # Business Logic (NarrativeController)
├── services/        # Data Management (SnapshotService)
└── api/             # API endpoints (routes.py)
    main.py, database.py, models.py, schemas.py

Root files:
requirements.txt, run.py, test_api.py, README.md
```

**Structure Approach:**
- Clear separation: Agents (AI), Controllers (validation), Services (data), API (endpoints)
- Each layer has a single responsibility
- Easy to extend with new agents, rules, or endpoints

## What Will Be Delivered

### Complete Base Schemas
- **Regions**: Name, climate, terrain, description, resources, cities
- **Cities**: Name, population, region, resources, factions, description
- **Resources**: Name, type, abundance, description
- **Factions**: Name, type, influence (0-100), description

### Three AI Agents
1. **WorldDesigner**: Generates complete world structure (regions, cities, resources, factions)
2. **ContentBuilder**: Enriches world data and generates event proposals
3. **EventsAgent**: Proposes logical events based on current world state

All agents return structured JSON and include fallback logic for reliability.

### NarrativeController
Validates events using 3 rules:
1. **Target Exists**: Event target (region/city/faction) must exist in the world
2. **No Negative Population**: Population changes cannot result in negative values
3. **Logical Effects**: Effects must match event type (e.g., disasters reduce population)

### API Endpoints
- `POST /api/generate_world` - Generate a new world and create snapshot
- `POST /api/propose_events` - Propose and validate events for current world
- `GET /api/snapshots` - List all world snapshots
- `GET /api/snapshots/{version}` - Get specific snapshot by version
- `GET /api/current_world` - Get latest world state

### Snapshot/Versioning System
- Automatic incremental version numbers
- Complete world state stored as JSON in each snapshot
- Rollback capability to any previous version

### Documentation
- Complete README with setup instructions
- Architecture overview document
- Code comments and docstrings throughout
- Test script to verify functionality

## Quick Start (After Delivery)

Once you have the repository, run this single command:

```bash
python setup_and_run.py
```

This will:
1. Check and install dependencies
2. Start the server
3. Generate a sample world
4. Save snapshot to `storage/snapshots/`

The server will be running at `http://localhost:8000` with API docs at `/docs`.

Example snapshot JSON files will be available in `storage/snapshots/` folder.

Looking forward to building this with you!

WorldForgeAPI

WorldForgeAPI Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

WorldForgeAPI

WorldForgeAPI Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README