sortedcord/omnia-consolidated
1
0
Fork 0
mirror of https://github.com/sortedcord/omnia.git synced 2026-09-05 05:43:47 +05:30
Code Issues Packages Projects Releases Wiki Activity

feat(api): Created openapi based pubic API contracts

Browse Source 
- made DTOs
- created an api-client
This commit is contained in:
Aditya Gupta
2026-08-03 11:06:02 +00:00
parent 8204e9c18e
commit 81152dc8de
25 changed files with 1171 additions and 112 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
web/docs/src/content/docs/architecture/actor.md
View File

@@ -60,8 +60,7 @@ Monologue (`"monologue"`) is the third intent type. Its properties:
│ → system prompt + user context (subjective world + memory + time)
│
├─ 2. IActorProseGenerator.generate(entityId, systemPrompt, userContext)
│ ├─ LLMActorProseGenerator: queries LLM via generateStructuredResponse
│ └─ CLIProseGenerator: prompts human player via CLI / readline interface
│ └─ LLMActorProseGenerator: queries LLM via generateStructuredResponse
│ → narrativeProse: string
│
├─ 3. IntentDecoder.decode(worldState, actorId, prose)
@@ -69,7 +68,7 @@ Monologue (`"monologue"`) is the third intent type. Its properties:
│
└─ returns { narrativeProse, intents }
[Caller (e.g. game loop)]
[Runtime turn executor]
│
├─ for each intent in intents:
│ ├─ if intent.type === "monologue": short-circuit, write to buffer
@@ -79,6 +78,11 @@ Monologue (`"monologue"`) is the third intent type. Its properties:
└─ world state persisted to DB
```
Human-controlled turns bypass NPC prose generation. `@omnia/runtime` prepares
a waiting-player snapshot, the GUI collects prose, and
`RuntimeService.submitPlayerAction()` sends it through intent decoding and turn
execution.
## Key Files
| File | Role |

9
web/docs/src/content/docs/architecture/llm-providers.md
View File

@@ -58,7 +58,7 @@ Configurations are stored globally in `data/settings.db` (separated from specifi
## Task Provider Routing
During a simulation run, the engine executes four distinct LLM operations. To optimize costs, latency, or model accuracy, you can route each of these tasks to different LLM provider instances:
During a simulation run, the runtime executes five generative operations and one embedding operation. To optimize costs, latency, or model accuracy, you can route each task to a different provider instance:
| Task Name | Key ID | Description | Default Model |
| :------------------------- | :--------------- | :--------------------------------------------------------------------------------------- | :--------------------------------------------- |
@@ -66,6 +66,8 @@ During a simulation run, the engine executes four distinct LLM operations. To op
| **LLM Validator** | `llm-validator` | Arbitrates and validates proposed actions against the world state rules and constraints. | `gemini-2.5-flash` / `google/gemini-2.5-flash` |
| **Intent Decoder** | `intent-decoder` | Parses and splits free-text actions/prose into structured intent sequences. | `gemini-2.5-flash` / `google/gemini-2.5-flash` |
| **TimeDelta Generator** | `timedelta` | Calculates the duration of character actions to advance the game clock. | `gemini-2.5-flash` / `google/gemini-2.5-flash` |
| **Memory Handoff Engine** | `handoff` | Summarizes Cognitive Buffer entries into the Memory Ledger. | Active generative provider |
| **Text Embeddings** | `embeddings` | Generates vectors for Memory Ledger retrieval. | Active embedding provider |
If no specific provider instance is mapped to a task, the task automatically routes to the globally marked **Active** provider instance.
@@ -73,11 +75,12 @@ If no specific provider instance is mapped to a task, the task automatically rou
## CLI Setup & Seeding
Rather than automatically bootstrapping from environment variables at runtime, which adds runtime complexity, you can quickly seed the database using the CLI setup tool:
Provider instances can be configured in the GUI or seeded from environment variables with the CLI setup tool. The CLI requires compiled workspace output, so run `pnpm build` first.
### Seeding All Environment-Variable Providers
```bash
pnpm build
pnpm setup-provider --all
```
@@ -91,7 +94,7 @@ pnpm setup-provider --provider google-genai --key YOUR_API_KEY [--name "My Gemin
### Environment Variable Fallback
If the database contains no active provider instances, the LLM providers (e.g. `GeminiProvider`, `OpenAIProvider`, etc.) will fall back directly to reading their keys from environment variables (e.g. `GOOGLE_API_KEY`, `OPENAI_API_KEY`) via `resolveCredentials`.
When `GOOGLE_API_KEY` is present and no suitable active instance exists, `@omnia/runtime` creates Google generative and embedding fallback instances in `data/settings.db`. Other provider environment variables can be seeded with `pnpm setup-provider --all`.
---

17
web/docs/src/content/docs/architecture/overview.md
View File

@@ -16,8 +16,9 @@ omnia/
spatial/ location and POI graph, portal-based perception
llm/ ILLMProvider interface plus Gemini and deterministic mock implementations
scenario/ scenario JSON schema and loader (JSON → SQLite)
runtime/ session lifecycle, turn execution, provider routing, and simulation persistence
apps/
cli/ the playable loop (human or LLM actors, --scenario / --play flags)
gui/ Next.js UI and server actions; instantiates RuntimeService
content/
demo/ bundled scenarios (talking-room)
tests/
@@ -30,13 +31,17 @@ omnia/
The engine core deliberately knows nothing about domain content (stats, traits, genres). Scenarios are plain JSON the loader ingests; what an attribute means is the scenario's business, not the engine's.
`@omnia/runtime` is an application library hosted by the Next.js server, not a
separately deployed backend service. Browser requests reach GUI server actions,
which delegate simulation lifecycle and turn execution to `RuntimeService`.
## Core Data Flow
1. An **Actor Agent** receives an epistemically-bounded view of the world and produces narrative prose.
2. The **Intent Decoder** splits prose into typed intents (`dialogue`, `action`, `monologue`).
3. The **World Architect** validates action intents against objective world state and generates structured deltas.
4. Deterministic code applies deltas to the **World State** (SQLite) and persists results.
5. Memory entries are written per-character, filtered through **Subjective Aliases**.
1. A browser action reaches a Next.js server action in `apps/gui`.
2. `RuntimeService` loads the session and asks an **Actor Agent** for narrative prose when the active entity is an NPC.
3. The **Intent Decoder** splits prose into typed intents (`dialogue`, `action`, `monologue`).
4. The **World Architect** validates action intents against objective world state and generates structured deltas.
5. Deterministic code applies deltas to the **World State** (SQLite), writes per-character memory through **Subjective Aliases**, and persists the runtime session.
## A Research Instrument