WorldForgeAPI

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 13 Open GitHub ↗

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

// 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

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README