simula 0.1.0__tar.gz

simula-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Ofovik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

simula-0.1.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include LICENSE
+include PLAN.md
+include PRINCIPLES.md
+include simula.toml.example
+recursive-include schemas *.json
+recursive-include grammars *.gbnf
+include simula/py.typed

simula-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: simula
+Version: 0.1.0
+Summary: Lokalno-prvi pogon za sazdavanje i naseljavanje svetova i persona iz korisnikovih materijala.
+Author-email: Peter Ofovik <pedjaurosevic@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/pedjaurosevic/simula
+Project-URL: Repository, https://github.com/pedjaurosevic/simula
+Keywords: llm,simulation,worldbuilding,persona,local-first,llama.cpp,gbnf
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: platformdirs>=4.0
+Provides-Extra: openai
+Requires-Dist: requests>=2.28; extra == "openai"
+Provides-Extra: embeddings
+Requires-Dist: sentence-transformers>=2.2; extra == "embeddings"
+Dynamic: license-file
+
+# simula
+
+**A local-first engine for generating and inhabiting worlds and personas from your own materials.**
+
+One engine, two blueprint types (`world` | `persona`), one unified entity model (`Simulacrum`).
+Local-first (llama.cpp + GBNF for hard-constrained output), but always able to run against any
+OpenAI-compatible endpoint.
+
+> **Status:** early alpha (Phase 0). The core is still a skeleton — see [`PLAN.md`](PLAN.md) for the
+> implementation phases and [`PRINCIPLES.md`](PRINCIPLES.md) for the empirically derived lessons
+> that drive the design.
+
+## Install
+
+```bash
+pip install simula
+```
+
+## Quick start
+
+```bash
+simula --version
+simula init          # create a workspace (materials/ blueprints/ saves/ evals/)
+simula where         # print the workspace path
+```
+
+The workspace lives at a platform-appropriate path (via `platformdirs`), falling back to
+`~/simula-workspace`. **No corpus is ever shipped** — you bring your own materials.
+
+## Configuration
+
+Copy `simula.toml.example` into your workspace as `simula.toml` and edit the backend (llama.cpp or
+OpenAI-compatible), embeddings, RAG, and experience mode (`world` | `persona`).
+
+## Design in brief
+
+- **Constrained output is the reliability backbone:** GBNF on llama.cpp's `/completion`,
+  `json_schema` on OpenAI-compatible backends, with a parse-and-repair fallback.
+- **Minimal prompt:** a commit directive + the blueprint spine + pointers into your materials (RAG),
+  not a large ontology.
+- **Local-first and private:** embeddings and generation can stay on your own machine.
+- **The engine holds the truth:** the LLM only *proposes* structured changes; the engine validates
+  and applies them against authoritative state.
+
+## Documentation
+
+Full docs: **https://pedjaurosevic.github.io/simula/**
+
+## License
+
+MIT — see [LICENSE](LICENSE).

simula-0.1.0/PLAN.md

@@ -0,0 +1,275 @@
+# simula — PLAN
+
+> A local-first engine for generating and inhabiting fashioned worlds and personas from the
+> user's own materials. One engine, two blueprint types, one unified entity model.
+> The name carries a question, not a claim: is a fashioned mind/world real? (PKD)
+
+This document is the design plan. Code, schemas, and config are all in English (portability, GitHub).
+
+---
+
+## 0. What simula is (and is NOT)
+
+**It is:** a thin harness that (1) takes the user's materials (books, texts), (2) distills a
+*blueprint* from them (the spine of a world or a persona — mostly pointers into the material plus a
+tiny summary), and (3) runs an interactive, stateful, memory-bearing experience in which the LLM
+**proposes** structured changes while the engine **holds the truth**.
+
+**It is NOT:** a world generator "out of thin air," an elaborate cognitive architecture, or a Zork
+fork. Zork is a fixed authored world; we build a world *from a corpus*. (See `PRINCIPLES.md` for
+why — these are lessons from our experiment series, not style.)
+
+Two implementations over the same core:
+- **simula worldbuilding** — a TUI/web game; the user walks through a world generated from their
+  books. The founding idea; we build it first.
+- **simula persona** — the same concept applied to creating a persona (Big Five / OCEAN substrate
+  via IPIP, public domain × the user's material). Second phase.
+
+A key idea: a persona created in *persona* mode can live inside a world from *worldbuilding* mode.
+This is NOT an add-on — it is exactly what the unified entity model exists for (section 4).
+
+---
+
+## 1. The unified entity model — the heart of the design
+
+Everything in simula is a **simulacrum**:
+
+```
+Simulacrum = (Blueprint, State, Memory, Contract)
+```
+
+- **Blueprint** — the distilled spine: WHAT the entity is. Mostly pointers into materials plus a
+  short summary. NOT a large ontology (the B'=B lesson: ontology is decoration; grounding on the
+  text carries the consequence).
+- **State** — the deterministic source of truth held by the *engine*, not the model.
+- **Memory** — short-term (transcript window) + long-term (fact ledger, history) + search (RAG)
+  over both. This is the "remember."
+- **Contract** — the grammar/schema the LLM MUST emit to propose a delta (narration + state change).
+  Structure at the boundary, free reasoning inside.
+
+Everything follows from this:
+- **World** = a simulacrum whose state is the *environment* (places, objects, NPCs, time), and the
+  loop is exploration.
+- **Persona** = a simulacrum whose state is the *agent* (mood, knowledge, relationship, goals), and
+  the loop is conversation.
+- **NPC** = a persona-simulacrum *embedded* in a world-simulacrum. When the player talks to it, the
+  world loop delegates that entity's turn to the persona loop, then returns the result as a world
+  delta.
+
+That is why persona-in-world is a **composition of simulacra**, not new machinery. You build one
+entity abstraction and two blueprint schemas; the crossover is free (but *ships* last — section 4).
+
+---
+
+## 2. Layers
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Clients (thin):  TUI (Textual)   |   Web UI (FastAPI)   │
+├─────────────────────────────────────────────────────────┤
+│  simula-core (library)                                   │
+│   • Backend abstraction (llama.cpp local | OpenAI-compat)│
+│   • Constrained output (GBNF local | json_schema/tools)  │
+│   • RAG (sqlite-vec + FTS5, e5-small embeddings)         │
+│   • State engine (sqlite, source of truth) + Fact ledger │
+│   • Memory (short/long-term + search)                    │
+│   • Turn loop (ORORO-minimal)                            │
+│   • Eval rig (style-fidelity, drift, commit-rate)        │
+├─────────────────────────────────────────────────────────┤
+│  Blueprint layer:  World blueprint  |  Persona blueprint │
+├─────────────────────────────────────────────────────────┤
+│  Workspace:  ~/simula-workspace/  (sqlite, materials)    │
+└─────────────────────────────────────────────────────────┘
+```
+
+Clients are thin — all logic is in `simula-core`. TUI and web are two skins over the same core.
+
+---
+
+## 3. Turn loop (ORORO-minimal)
+
+One turn, identical for world and persona (the difference is only the blueprint and the delta
+schema):
+
+1. **Observe** — take the user's input.
+2. **Retrieve** — RAG fetches relevant passages from the materials + relevant facts from the ledger
+   (grounding against *narrative* drift, not just bookkeeping drift).
+3. **React** — assemble a MINIMAL prompt: commit directive + blueprint spine + retrieved exemplars
+   + current state + transcript window + user input.
+4. **Constrain** — call the backend with a contract (GBNF locally / json_schema on OpenAI-compat).
+   Output = `{ narration, deltas[] }`, guaranteed parsable.
+5. **Validate & apply** — the engine checks deltas against state and the ledger (reject invalid ones
+   — e.g., taking an object that isn't there), applies the valid ones, writes to the ledger.
+6. **Persist & render** — save state, render the narration.
+
+The commit directive is the most valuable part of the prompt (lesson from the tests: the model's
+failure mode is hedging → generic mush). Roughly: *"Commit to a concrete, tangible detail rooted in
+the texture of this world/persona. Never retreat into generic fantasy or vagueness."*
+
+---
+
+## 4. Persona-in-world — my view
+
+The idea is good and not peripheral: it is the *reason* the entity model is unified. If both world
+and persona are "simulacrum = (blueprint, state, memory, contract)," then a persona in a world is
+just a rich NPC — the world loop delegates its turn to the persona loop. The abstraction allows it
+from day one, so we should design it *in* immediately (uniform entities), even before we use it.
+
+But honestly about the cost, so we don't build it too early:
+- Two LLM-driven entities, each with their own state, mean *two* calls per turn (latency) and
+  *multiplied* drift risk — the persona must stay true to itself AND fit the world's tone.
+- That is the hardest coherence case. The "measure where it fails" lesson: don't build the hardest
+  thing first.
+
+So: **the architecture allows it from the start, but it ships last** (Phase 6), only once the eval
+rig shows that the drift of a *single* entity is under control. Love the idea, defer the execution.
+
+---
+
+## 5. Backend abstraction (local-first, but always OpenAI-compat)
+
+One interface, two adapters (see `simula/backends.py`):
+
+```
+complete(messages, *, contract=None, temperature, max_tokens) -> str
+```
+
+- **LlamaCppBackend** (primary): HTTP to a local server (:18083). Constrained output via a
+  **GBNF grammar** (the `grammar` field) — a guarantee of valid JSON at decode time. Embeddings
+  local (e5-small). This is the default.
+- **OpenAICompatBackend**: any OpenAI-compatible endpoint + key + model. Constrained output via
+  `response_format: json_schema` or tool-calling; a parse-and-repair fallback loop if the model
+  doesn't support it. Embeddings: either their endpoint or still local e5 (recommended: local e5,
+  to avoid coupling).
+
+The backend choice lives in `simula.toml` in the workspace. The "Contract" is the structured-output
+abstraction implemented differently per backend — it is the reliability backbone.
+
+---
+
+## 6. Workspace (installed on the user's machine)
+
+Location via `platformdirs` (cross-platform), default `~/simula-workspace/`:
+
+```
+simula-workspace/
+  simula.toml             # config: backend, endpoint, model, key, experience mode
+  materials/              # the user's books/texts (theirs, local)
+  library.sqlite          # RAG (sqlite-vec + FTS5) + state + memory + ledger
+  blueprints/             # distilled world/persona blueprints (JSON)
+  saves/                  # experience snapshots / transcripts
+  evals/                  # eval rig results
+```
+
+The user adds books through the TUI or web (which copies them into `materials/` and runs the
+ingest). Everything is inspectable and portable. **We do not ship a corpus** — the user brings
+their own (section 9).
+
+---
+
+## 7. Cross-platform
+
+The core is Python (Linux/Mac/Windows). Rules:
+- No Linux-only dependencies; `pathlib` everywhere, no bash assumptions in the core.
+- TUI: **Textual** (modern, cross-platform). Web: **FastAPI** + a thin frontend.
+- sqlite-vec works cross-platform; e5-small via `sentence-transformers`/`llama.cpp` embeddings.
+- The llama.cpp backend is just HTTP to a server the user runs (or uses OpenAI-compat), so the core
+  doesn't depend on the server's platform.
+- Workspace locations via `platformdirs`.
+
+You develop on Linux Mint; CI tests Win/Mac too (a matrix) before every release.
+
+---
+
+## 8. Reliability: against drift
+
+Two levels of drift, two cures:
+- **Bookkeeping** (inventory, location): state outside the model + constrained deltas + validation
+  in the engine. The model proposes, the engine adjudicates.
+- **Narrative/tonal/factual** (forgets an established fact, betrays the tone, contradicts itself):
+  RAG grounding on the materials every turn + a **fact ledger** (a running record of established
+  facts) that is both retrieved and used to validate contradictions.
+
+The second level is the real hard problem (the "measure where it fails" lesson). simula's
+engineering value lives there, not in the beauty of a single turn.
+
+---
+
+## 9. Copyright / IP (important for a public GitHub)
+
+- We ship the **engine, never the corpus**. The user brings their own books into `materials/`.
+- The blueprint extracts *texture* (tone, motifs, structure, lexicon as pointers), it does not
+  reproduce text. Add a guard against long verbatim passages in the narration.
+- Result: a world *in the texture* of some author, not a transcript. Legal hygiene and better art.
+
+---
+
+## 10. Eval rig — the backbone, not an afterthought
+
+Repurposes our apparatus from the test series (conditions, ablation, pre-registration). It measures:
+- **style-fidelity** — embedding distance of the output to the corpus (does it sound like the
+  world/persona).
+- **drift** — the number of contradictions of the output against the fact ledger across N turns.
+- **commit-rate** — the fraction of turns with a concrete, anchored detail vs generic mush
+  (anti-mush; measures whether the commit directive works).
+
+Every prompt/RAG/backend change passes a fast ablation before adoption. Every phase has an eval gate.
+
+---
+
+## 11. Persona blueprint — Big Five / OCEAN via IPIP (and NOT MBTI/16Personalities)
+
+The persona substrate is **Big Five / OCEAN**, instantiated via **IPIP** items — which are in the
+**public domain** (https://ipip.ori.org), free to copy, modify, translate, and use commercially,
+without permission or fee. This is a deliberate choice, both legal and scientific:
+
+- **Legally (important for a public GitHub release):** MBTI is a trademark of the Myers-Briggs
+  company and a licensed instrument; 16Personalities is NOT MBTI but the NERIS framework with its
+  own brand, descriptions, archetype names ("Advocate," etc.), and graphics — all their property.
+  We do not reproduce their text, type names, or brand. The typology itself (the idea of axes,
+  four-letter labels) is not copyrightable, but because we ship a public, commercially usable
+  engine, we do not rely on a "hobby/personal" exception — we choose a clean public-domain
+  substrate. (This is not legal advice; specifics vary for Serbia/EU vs US users of the repo.)
+- **Scientifically:** OCEAN is empirically robust and falsifiable, unlike MBTI dichotomies. That
+  matches the ethos of the test series (PRINCIPLES.md): measurable and honest, not a clinical claim.
+
+Mapping: five **continuous** axes (O, C, E, A, N in [0,1]) → behavioral tendencies, register/voice
+(from the materials if the persona is "after" a corpus), values, mannerisms, an own "history" in
+memory. If a discrete seed is needed for generative convenience, we **bucket the continuous scores
+into our own archetypes with our own names and descriptions** (the `archetype` field, optional) —
+never anyone else's names or text. See `schemas/persona_blueprint.schema.json` (`ocean` instead of
+the old `lattice`).
+
+---
+
+## 12. Build phases (each with an eval gate)
+
+- **Phase 0 — skeleton.** Workspace bootstrap, config, backend adapter (llama.cpp + openai),
+  contract abstraction, a "hello world" turn loop end-to-end on *empty* content. (First make it work
+  end-to-end on empty, then add pieces.)
+- **Phase 1 — ingest + RAG.** Add books → chunk → embed → retrieve. Gate: retrieval relevance on
+  manual queries.
+- **Phase 2 — worldbuilding (the founding idea).** World DISTILL (corpus → world blueprint) +
+  worldbuilding PLAY loop + STATE + fact ledger. TUI client. First playable world: **Kipple** (PKD).
+- **Phase 3 — eval rig.** style-fidelity, drift, commit-rate; ablate prompt/RAG choices. Gate:
+  drift under control across a long session.
+- **Phase 4 — persona.** Persona DISTILL (OCEAN/IPIP substrate × material → persona blueprint) +
+  persona PLAY loop (conversation, consistency).
+- **Phase 5 — web UI.** A thin client over the core (FastAPI). Adding books through the web.
+- **Phase 6 — persona-in-world.** The uniform entity model pays off: a persona as a rich NPC. Only
+  once Phase 3 shows controlled drift for a single entity.
+
+The rule across all phases: add a component only when ablation shows a delta or prevents a
+regression. The thinnest harness that works, then growth by proof — the inverse of "970/1000 of
+machinery richness."
+
+---
+
+## 13. Explicit non-goals (anti-inflation)
+
+- No large world ontology in the prompt (pointers + spine instead).
+- No rigid multi-step reasoning templates in the system prompt (rigidity hurts — see dim_masina in
+  `PRINCIPLES.md`).
+- No self-modifying "super-exo" layer in v1 (defeasible heuristics later, if ablation asks).
+- No LangChain or heavy abstractions — direct calls.
+- No Z-machine/Zork fork — the wrong foundation for corpus→world.

simula-0.1.0/PRINCIPLES.md

@@ -0,0 +1,48 @@
+# PRINCIPLES — lessons the test series earned
+
+This file exists so that a future builder (human or agent) does not push the project back into
+over-design. Everything below is *empirically derived* from a series of experiments on sign-type
+discrimination on Gemma 12B (local, llama.cpp), not a stylistic preference. The details are in the
+project history; here are the engineering consequences.
+
+## 1. The 12B model's failure mode is OVER-HEDGING, not false affirmation.
+Without a frame, the model rejects even valid conclusions. Replicated across three versions
+(license-acc bare: 0.00 → 0.14 → 0.44; always the lowest). Consequence: the most valuable part of
+the prompt is the *commit directive* ("commit to the concrete, don't hedge without reason"). In
+narration this translates to: a concrete, anchored detail instead of generic mush.
+
+## 2. The content of the frame is often irrelevant; the effect is "attention/de-hedging," not ontology.
+B' = B = 1.00: empty hermeneutic jargon licenses just as well as naming the exact concepts. Two
+full conditions maxed out every item. Consequence: **ontology/persona is decoration until ablation
+proves otherwise.** Blueprint = pointers into the material + a tiny spine, not a large ontology.
+
+## 3. An elaborate procedure does not beat plain framing — and can trip you up.
+Operational procedure C did not outperform priming, and in one case (dim_masina) its own rigid step
+led it into an error that a freer model avoided. Consequence: no rigid reasoning templates in the
+system prompt. Structure goes on the I/O boundary, not into the model's head.
+
+## 4. State and facts live OUTSIDE the model; the model proposes constrained deltas.
+The only structure that worked everywhere and never hurt was forced, parsable output. Consequence:
+GBNF (local) / json_schema (OpenAI-compat) for deltas; the engine is the source of truth.
+
+## 5. Drift is the real front. Measure where the model actually fails.
+Ceiling-saturated metrics teach nothing (block-acc was 1.00 everywhere → a dead signal).
+Consequence: don't spend measurement on what the model already passes; target long-horizon
+coherence (narrative/factual drift), not the beauty of a single turn.
+
+## 6. The eval rig is the product; the skeleton/prompt is a consumable.
+Every "richer is better" intuition fell as soon as a real control was added — three times.
+Consequence: on 12B you don't trust prompt intuition; every change passes a differential eval
+(condition A/B + ablation + a pre-registered threshold). It is a permanent part of the system, not a
+one-off experiment.
+
+## 7. The lessons are scale-dependent.
+On 4B, empty verbosity HURTS, and naming the types helps (the opposite of 12B). Consequence: if
+simula falls back to a smaller model (fallback machines), the prompt strategy is NOT the same — more
+skeleton for the smaller, less for the larger. Don't assume the 12B recipe works on 4B.
+
+## 8. Build the thinnest, grow by proof.
+The strongest move of the whole series would be: start from the thinnest harness, add piece by piece
+only when ablation shows a delta. This is the inverse of plans that score high on *machinery
+richness* they cannot show actually works. Tokens and rigidity are paid for; the benefit must be
+proven.

simula-0.1.0/README.md

@@ -0,0 +1,51 @@
+# simula
+
+**A local-first engine for generating and inhabiting worlds and personas from your own materials.**
+
+One engine, two blueprint types (`world` | `persona`), one unified entity model (`Simulacrum`).
+Local-first (llama.cpp + GBNF for hard-constrained output), but always able to run against any
+OpenAI-compatible endpoint.
+
+> **Status:** early alpha (Phase 0). The core is still a skeleton — see [`PLAN.md`](PLAN.md) for the
+> implementation phases and [`PRINCIPLES.md`](PRINCIPLES.md) for the empirically derived lessons
+> that drive the design.
+
+## Install
+
+```bash
+pip install simula
+```
+
+## Quick start
+
+```bash
+simula --version
+simula init          # create a workspace (materials/ blueprints/ saves/ evals/)
+simula where         # print the workspace path
+```
+
+The workspace lives at a platform-appropriate path (via `platformdirs`), falling back to
+`~/simula-workspace`. **No corpus is ever shipped** — you bring your own materials.
+
+## Configuration
+
+Copy `simula.toml.example` into your workspace as `simula.toml` and edit the backend (llama.cpp or
+OpenAI-compatible), embeddings, RAG, and experience mode (`world` | `persona`).
+
+## Design in brief
+
+- **Constrained output is the reliability backbone:** GBNF on llama.cpp's `/completion`,
+  `json_schema` on OpenAI-compatible backends, with a parse-and-repair fallback.
+- **Minimal prompt:** a commit directive + the blueprint spine + pointers into your materials (RAG),
+  not a large ontology.
+- **Local-first and private:** embeddings and generation can stay on your own machine.
+- **The engine holds the truth:** the LLM only *proposes* structured changes; the engine validates
+  and applies them against authoritative state.
+
+## Documentation
+
+Full docs: **https://pedjaurosevic.github.io/simula/**
+
+## License
+
+MIT — see [LICENSE](LICENSE).

simula-0.1.0/grammars/turn_output.gbnf

@@ -0,0 +1,31 @@
+# turn_output.gbnf
+# Hard-constrains llama.cpp output to a valid TurnOutput JSON object (see schemas/turn_output.schema.json).
+# Pass via the `grammar` field of llama.cpp's native /completion endpoint.
+# This is the reliability backbone on the local backend: valid structure is GUARANTEED at decode time,
+# not hoped for. (PRINCIPLES.md #4)
+
+root   ::= obj
+obj    ::= "{" ws "\"narration\"" ws ":" ws string ws "," ws "\"deltas\"" ws ":" ws deltas ws "}"
+
+deltas ::= "[" ws ( delta ( ws "," ws delta )* )? ws "]"
+delta  ::= "{" ws
+             "\"op\"" ws ":" ws op ws "," ws
+             "\"target\"" ws ":" ws string
+             ( ws "," ws "\"value\"" ws ":" ws value )?
+             ( ws "," ws "\"reason\"" ws ":" ws string )?
+           ws "}"
+
+op     ::= "\"set\"" | "\"add\"" | "\"remove\"" | "\"move\"" | "\"flag\"" | "\"fact\""
+
+value  ::= string | number | "true" | "false" | "null"
+
+string ::= "\"" char* "\""
+char   ::= [^"\\] | "\\" ( ["\\/bfnrt] | "u" hex hex hex hex )
+hex    ::= [0-9a-fA-F]
+
+number ::= "-"? int frac? exp?
+int    ::= "0" | [1-9] [0-9]*
+frac   ::= "." [0-9]+
+exp    ::= ("e" | "E") ("+" | "-")? [0-9]+
+
+ws     ::= [ \t\n\r]*

simula-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "simula"
+version = "0.1.0"
+description = "Lokalno-prvi pogon za sazdavanje i naseljavanje svetova i persona iz korisnikovih materijala."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Peter Ofovik", email = "pedjaurosevic@gmail.com" }]
+keywords = ["llm", "simulation", "worldbuilding", "persona", "local-first", "llama.cpp", "gbnf"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "platformdirs>=4.0",
+]
+
+[project.optional-dependencies]
+openai = ["requests>=2.28"]
+embeddings = ["sentence-transformers>=2.2"]
+
+[project.urls]
+Homepage = "https://github.com/pedjaurosevic/simula"
+Repository = "https://github.com/pedjaurosevic/simula"
+
+[project.scripts]
+simula = "simula.__main__:main"
+
+[tool.setuptools]
+packages = ["simula"]
+
+[tool.setuptools.package-data]
+simula = ["py.typed"]

simula-0.1.0/schemas/persona_blueprint.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "PersonaBlueprint",
+  "description": "Distilled spine of a persona. The trait substrate is Big Five / OCEAN, instantiated via public-domain IPIP item pools (https://ipip.ori.org, public domain). Used ONLY as a deterministic character-generation substrate, NOT as validated clinical psychology (see PLAN.md #11). No MBTI/16Personalities/NERIS marks, type names, or descriptions are used (legal hygiene for public release). Mostly pointers into materials + tiny spine, same discipline as WorldBlueprint.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "name", "ocean", "voice", "values"],
+  "properties": {
+    "id": { "type": "string" },
+    "name": { "type": "string" },
+    "source_note": { "type": "string" },
+    "ocean": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Big Five / OCEAN as a generative substrate (IPIP, public domain). Each axis is a continuous position in [0,1], not a diagnosis. Continuous so the engine can derive tendencies; discretize into archetypes only if desired.",
+      "required": ["openness", "conscientiousness", "extraversion", "agreeableness", "neuroticism"],
+      "properties": {
+        "openness": { "type": "number", "minimum": 0, "maximum": 1 },
+        "conscientiousness": { "type": "number", "minimum": 0, "maximum": 1 },
+        "extraversion": { "type": "number", "minimum": 0, "maximum": 1 },
+        "agreeableness": { "type": "number", "minimum": 0, "maximum": 1 },
+        "neuroticism": { "type": "number", "minimum": 0, "maximum": 1 }
+      }
+    },
+    "archetype": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "OPTIONAL discrete seed for generative convenience: our OWN named archetype derived by bucketing the continuous OCEAN scores. Name and description MUST be original (never 'Advocate', 'Logician', etc. or any NERIS/MBTI text).",
+      "required": ["name", "summary"],
+      "properties": {
+        "name": { "type": "string", "description": "Original archetype label. Project-owned, not borrowed from any type system." },
+        "summary": { "type": "string", "description": "1-2 sentence original description of the archetype's flavor." }
+      }
+    },
+    "voice": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["summary", "exemplar_refs"],
+      "properties": {
+        "summary": { "type": "string", "description": "Register, cadence, verbal tics in 1-3 sentences." },
+        "exemplar_refs": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "RAG chunk ids exemplifying the voice (if persona is derived from a corpus). POINTERS only."
+        }
+      }
+    },
+    "values": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "What the persona cares about / will defend or pursue."
+    },
+    "quirks": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Behavioral tendencies / mannerisms derived from the OCEAN substrate + materials."
+    },
+    "boundaries": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Consistency constraints the engine enforces (things the persona would not say/do)."
+    },
+    "history": {
+      "type": "string",
+      "description": "Backstory seed that seeds long-term memory at instantiation."
+    }
+  }
+}

simula-0.1.0/schemas/turn_output.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "TurnOutput",
+  "description": "What the LLM must emit each turn. The engine owns truth; the model only PROPOSES deltas. Validated and applied by the engine, never trusted blindly.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["narration", "deltas"],
+  "properties": {
+    "narration": {
+      "type": "string",
+      "description": "Prose shown to the player. Must be concrete and grounded in blueprint texture; never generic mush (see commit-directive)."
+    },
+    "deltas": {
+      "type": "array",
+      "description": "Proposed state changes. Empty array is valid (pure description / refused action).",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["op", "target"],
+        "properties": {
+          "op": {
+            "type": "string",
+            "enum": ["set", "add", "remove", "move", "flag", "fact"],
+            "description": "set: set a state field; add/remove: inventory or set membership; move: relocate entity; flag: boolean world flag; fact: append an established fact to the ledger."
+          },
+          "target": {
+            "type": "string",
+            "description": "Dotted path or entity id the op applies to, e.g. 'player.location', 'inventory', 'npc.rachel.mood'."
+          },
+          "value": {
+            "description": "New value / item / fact text. Type depends on op.",
+            "type": ["string", "number", "boolean", "null"]
+          },
+          "reason": {
+            "type": "string",
+            "description": "Optional short justification, grounded in retrieved material or ledger. Used by the engine for validation/audit."
+          }
+        }
+      }
+    }
+  }
+}

simula-0.1.0/schemas/world_blueprint.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "WorldBlueprint",
+  "description": "Distilled spine of a world. Deliberately small: mostly POINTERS into the user's materials plus a tiny summary. Not a big ontology (see PRINCIPLES.md #2).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "title", "tone", "rules", "lexicon", "seeds"],
+  "properties": {
+    "id": { "type": "string" },
+    "title": { "type": "string" },
+    "source_note": {
+      "type": "string",
+      "description": "Short note on provenance. Engine never ships source text; this references the user's own materials."
+    },
+    "tone": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["summary", "exemplar_refs"],
+      "properties": {
+        "summary": { "type": "string", "description": "1-3 sentences on register/mood." },
+        "exemplar_refs": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "RAG chunk ids that exemplify the tone. POINTERS, not copied text."
+        }
+      }
+    },
+    "rules": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "The world's 'physics'/conventions in a few terse lines (e.g. 'reality is unreliable; objects may be simulacra')."
+    },
+    "lexicon": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Signature vocabulary/coinages (e.g. 'kipple', 'kibble', 'empathy box')."
+    },
+    "seeds": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Starting scaffolding: a few places/factions/archetypes as light seeds, each linking to material.",
+      "properties": {
+        "places": { "type": "array", "items": { "$ref": "#/$defs/seed" } },
+        "factions": { "type": "array", "items": { "$ref": "#/$defs/seed" } },
+        "archetypes": { "type": "array", "items": { "$ref": "#/$defs/seed" } }
+      }
+    },
+    "opening": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Initial player state for a new save.",
+      "properties": {
+        "location": { "type": "string" },
+        "inventory": { "type": "array", "items": { "type": "string" } },
+        "intro": { "type": "string" }
+      }
+    }
+  },
+  "$defs": {
+    "seed": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string" },
+        "note": { "type": "string" },
+        "material_refs": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

simula-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

simula-0.1.0/simula/__init__.py

@@ -0,0 +1,15 @@
+"""simula — a local-first engine for generating and inhabiting worlds and personas from the
+user's own materials. See PLAN.md and PRINCIPLES.md.
+
+One engine, two blueprint types (world | persona), one unified entity model (Simulacrum).
+"""
+from .backends import Backend, Contract, Message, from_config
+from .loop import Simulacrum, TurnResult, run_turn
+from .workspace import bootstrap_workspace, default_workspace
+
+__all__ = [
+    "Backend", "Contract", "Message", "from_config",
+    "Simulacrum", "TurnResult", "run_turn",
+    "bootstrap_workspace", "default_workspace",
+]
+__version__ = "0.1.0"

simula-0.1.0/simula/__main__.py

@@ -0,0 +1,42 @@
+"""Minimal CLI entry point for `simula`.
+
+Currently (Phase 0) it only exposes `version`, `init` (workspace bootstrap), and `where`. The
+engine is still a skeleton; see PLAN.md for the implementation phases.
+"""
+from __future__ import annotations
+
+import argparse
+
+from . import __version__
+from .workspace import bootstrap_workspace, default_workspace
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="simula",
+        description="A local-first engine for generating and inhabiting worlds and personas.",
+    )
+    parser.add_argument("--version", action="version", version=f"simula {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    p_init = sub.add_parser("init", help="Create the workspace folder tree.")
+    p_init.add_argument("path", nargs="?", default=None, help="Path (default: platform default).")
+
+    sub.add_parser("where", help="Print the default workspace path.")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "init":
+        ws = bootstrap_workspace(args.path)
+        print(f"Workspace ready: {ws}")
+        return 0
+    if args.command == "where":
+        print(default_workspace())
+        return 0
+
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

simula-0.1.0/simula/backends.py

@@ -0,0 +1,109 @@
+"""Backend abstraction for simula.
+
+One interface, two adapters. Local-first (llama.cpp + GBNF) but always able to run against
+any OpenAI-compatible endpoint. "Constrained output" is the reliability backbone and is
+implemented differently per backend (PLAN.md #5, PRINCIPLES.md #4).
+
+This is a SKELETON: contracts + docstrings. Implement per build phases. stdlib only at the
+contract level; concrete adapters may use `requests`/`httpx` and `sentence-transformers`.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol, Sequence
+
+
+@dataclass(frozen=True)
+class Message:
+    role: str          # "system" | "user" | "assistant"
+    content: str
+
+
+@dataclass(frozen=True)
+class Contract:
+    """How to constrain structured output. Backend chooses how to honor it.
+
+    Exactly one of `gbnf_path` / `json_schema` is the primary mechanism; backends fall back
+    to a parse-and-repair loop if neither is supported.
+    """
+    gbnf_path: Path | None = None        # used by llama.cpp native /completion
+    json_schema: dict | None = None      # used by OpenAI-compat (response_format/tools)
+
+
+class Backend(Protocol):
+    """Text + embedding generation. Implementations MUST guarantee that, when a Contract is
+    given, the returned string parses against it (raising on irrecoverable failure)."""
+
+    def complete(
+        self,
+        messages: Sequence[Message],
+        *,
+        contract: Contract | None = None,
+        temperature: float = 0.2,
+        max_tokens: int = 800,
+    ) -> str:
+        ...
+
+    def embed(self, texts: Sequence[str]) -> list[list[float]]:
+        ...
+
+
+class LlamaCppBackend:
+    """Default, local. Talks to a llama.cpp server (e.g. :18083).
+
+    Constrained output: prefer the native /completion endpoint with a `grammar` (GBNF) field,
+    which guarantees valid structure at decode time. Embeddings stay local (e5-small).
+    """
+
+    def __init__(self, endpoint: str, model: str, *, prefer_native_grammar: bool = True) -> None:
+        self.endpoint = endpoint
+        self.model = model
+        self.prefer_native_grammar = prefer_native_grammar
+
+    def complete(self, messages, *, contract=None, temperature=0.2, max_tokens=800) -> str:
+        # Phase 0: implement.
+        # - If contract.gbnf_path and prefer_native_grammar: POST /completion with
+        #   {"prompt": render(messages), "grammar": gbnf_text, "temperature": ..., "n_predict": ...}
+        #   (Gemma: fold system into the prompt; see PRINCIPLES.md note on system role.)
+        # - Else: POST /v1/chat/completions (no hard grammar; rely on repair loop).
+        raise NotImplementedError
+
+    def embed(self, texts) -> list[list[float]]:
+        # Phase 1: local e5-small (sentence-transformers) or llama.cpp /embedding.
+        raise NotImplementedError
+
+
+class OpenAICompatBackend:
+    """Any OpenAI-compatible endpoint + key + model. Never store the key in config; read env."""
+
+    def __init__(self, base_url: str, api_key: str, model: str, *, structured_output: str = "json_schema") -> None:
+        self.base_url = base_url
+        self.api_key = api_key
+        self.model = model
+        self.structured_output = structured_output  # "json_schema" | "tools" | "repair"
+
+    def complete(self, messages, *, contract=None, temperature=0.2, max_tokens=800) -> str:
+        # Phase 0: implement.
+        # - structured_output == "json_schema": pass response_format with contract.json_schema.
+        # - "tools": expose a single tool whose params == contract.json_schema; force tool_choice.
+        # - "repair": free generation + JSON extraction + one repair retry.
+        raise NotImplementedError
+
+    def embed(self, texts) -> list[list[float]]:
+        # Default to local e5 even here (decoupling); only use remote embeddings if configured.
+        raise NotImplementedError
+
+
+def from_config(cfg: dict) -> Backend:
+    """Construct the backend from a parsed simula.toml dict. See simula.toml.example."""
+    kind = cfg["backend"]["kind"]
+    if kind == "llamacpp":
+        c = cfg["backend"]["llamacpp"]
+        return LlamaCppBackend(c["endpoint"], c["model"], prefer_native_grammar=c.get("prefer_native_grammar", True))
+    if kind == "openai_compat":
+        import os
+        c = cfg["backend"]["openai_compat"]
+        return OpenAICompatBackend(c["base_url"], os.environ[c["api_key_env"]], c["model"],
+                                   structured_output=c.get("structured_output", "json_schema"))
+    raise ValueError(f"unknown backend.kind: {kind}")

simula-0.1.0/simula/loop.py

@@ -0,0 +1,74 @@
+"""The turn loop and the unified entity model.
+
+Everything is a Simulacrum = (blueprint, state, memory, contract). A World is a simulacrum of
+place; a Persona is a simulacrum of agent; an NPC is a Persona embedded in a World. The loop is
+the same for both; only blueprint and applied-delta semantics differ. (PLAN.md #1, #3)
+
+SKELETON: contracts + docstrings.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .backends import Backend, Contract, Message
+
+
+@dataclass
+class Simulacrum:
+    """A world or a persona (or an NPC = persona-in-world)."""
+    id: str
+    kind: str                      # "world" | "persona"
+    blueprint: dict                # validated against schemas/*.schema.json
+    state: dict = field(default_factory=dict)   # engine-owned source of truth
+    # memory + ledger live in sqlite (library.sqlite); referenced by id, not held in RAM.
+
+
+@dataclass
+class TurnResult:
+    narration: str
+    applied: list[dict]            # deltas the engine actually applied (after validation)
+    rejected: list[dict]           # deltas rejected (invalid against state/ledger), for audit
+
+
+COMMIT_DIRECTIVE = (
+    "Commit to a concrete, tangible detail rooted in the texture of this world/persona. "
+    "Never retreat into generic fantasy or vagueness. If an action is not feasible, say why, "
+    "concretely."
+)  # The single highest-value prompt content (PRINCIPLES.md #1).
+
+
+def run_turn(
+    sim: Simulacrum,
+    player_input: str,
+    backend: Backend,
+    *,
+    retrieve,                       # callable(query, top_k) -> list[chunk]
+    ledger,                         # fact ledger interface (read/append/contradicts)
+    transcript_window: list[Message],
+    contract: Contract,
+    temperature: float = 0.2,
+    max_tokens: int = 800,
+) -> TurnResult:
+    """One ORORO-minimal turn (PLAN.md #3):
+
+    1. Observe   - player_input is given.
+    2. Retrieve  - grounding from materials + relevant ledger facts.
+    3. React     - assemble a MINIMAL prompt (commit-directive + blueprint spine +
+                   exemplars + current state + transcript window + input).
+    4. Constrain - backend.complete(..., contract=contract) -> guaranteed-parsable TurnOutput.
+    5. Validate  - check each delta against state + ledger; apply valid, reject invalid.
+    6. Persist   - caller persists state + appends to ledger/transcript.
+
+    Returns narration + applied/rejected deltas. Does NOT mutate sqlite directly; the caller
+    persists (keeps this function pure-ish and testable for the eval rig).
+    """
+    raise NotImplementedError
+
+
+def build_prompt(sim: Simulacrum, player_input: str, grounding: list, state: dict,
+                 transcript_window: list[Message]) -> list[Message]:
+    """Assemble the minimal prompt. Keep it thin: spine + pointers-grounding, not a big ontology
+    (PRINCIPLES.md #2)."""
+    raise NotImplementedError

simula-0.1.0/simula/workspace.py

@@ -0,0 +1,35 @@
+"""Workspace bootstrap. Cross-platform via platformdirs + pathlib (PLAN.md #6, #7).
+
+Creates ~/simula-workspace (or platform default) with the standard layout, and never ships
+any corpus: the user supplies their own materials (PLAN.md #9).
+
+SKELETON.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+LAYOUT = ["materials", "blueprints", "saves", "evals"]
+
+
+def default_workspace() -> Path:
+    """Platform-appropriate workspace path. Falls back to ~/simula-workspace."""
+    try:
+        import platformdirs
+        return Path(platformdirs.user_data_dir("simula")) / "workspace"
+    except Exception:
+        return Path.home() / "simula-workspace"
+
+
+def bootstrap_workspace(path: Path | None = None) -> Path:
+    """Create the workspace folder tree and a starter config if missing. Returns the path."""
+    ws = path or default_workspace()
+    ws.mkdir(parents=True, exist_ok=True)
+    for sub in LAYOUT:
+        (ws / sub).mkdir(exist_ok=True)
+    cfg = ws / "simula.toml"
+    if not cfg.exists():
+        # Phase 0: copy simula.toml.example into place.
+        pass
+    # Phase 1: initialize library.sqlite (sqlite-vec + FTS5 tables).
+    return ws

simula-0.1.0/simula.egg-info/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: simula
+Version: 0.1.0
+Summary: Lokalno-prvi pogon za sazdavanje i naseljavanje svetova i persona iz korisnikovih materijala.
+Author-email: Peter Ofovik <pedjaurosevic@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/pedjaurosevic/simula
+Project-URL: Repository, https://github.com/pedjaurosevic/simula
+Keywords: llm,simulation,worldbuilding,persona,local-first,llama.cpp,gbnf
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: platformdirs>=4.0
+Provides-Extra: openai
+Requires-Dist: requests>=2.28; extra == "openai"
+Provides-Extra: embeddings
+Requires-Dist: sentence-transformers>=2.2; extra == "embeddings"
+Dynamic: license-file
+
+# simula
+
+**A local-first engine for generating and inhabiting worlds and personas from your own materials.**
+
+One engine, two blueprint types (`world` | `persona`), one unified entity model (`Simulacrum`).
+Local-first (llama.cpp + GBNF for hard-constrained output), but always able to run against any
+OpenAI-compatible endpoint.
+
+> **Status:** early alpha (Phase 0). The core is still a skeleton — see [`PLAN.md`](PLAN.md) for the
+> implementation phases and [`PRINCIPLES.md`](PRINCIPLES.md) for the empirically derived lessons
+> that drive the design.
+
+## Install
+
+```bash
+pip install simula
+```
+
+## Quick start
+
+```bash
+simula --version
+simula init          # create a workspace (materials/ blueprints/ saves/ evals/)
+simula where         # print the workspace path
+```
+
+The workspace lives at a platform-appropriate path (via `platformdirs`), falling back to
+`~/simula-workspace`. **No corpus is ever shipped** — you bring your own materials.
+
+## Configuration
+
+Copy `simula.toml.example` into your workspace as `simula.toml` and edit the backend (llama.cpp or
+OpenAI-compatible), embeddings, RAG, and experience mode (`world` | `persona`).
+
+## Design in brief
+
+- **Constrained output is the reliability backbone:** GBNF on llama.cpp's `/completion`,
+  `json_schema` on OpenAI-compatible backends, with a parse-and-repair fallback.
+- **Minimal prompt:** a commit directive + the blueprint spine + pointers into your materials (RAG),
+  not a large ontology.
+- **Local-first and private:** embeddings and generation can stay on your own machine.
+- **The engine holds the truth:** the LLM only *proposes* structured changes; the engine validates
+  and applies them against authoritative state.
+
+## Documentation
+
+Full docs: **https://pedjaurosevic.github.io/simula/**
+
+## License
+
+MIT — see [LICENSE](LICENSE).

simula-0.1.0/simula.egg-info/SOURCES.txt

@@ -0,0 +1,23 @@
+LICENSE
+MANIFEST.in
+PLAN.md
+PRINCIPLES.md
+README.md
+pyproject.toml
+simula.toml.example
+grammars/turn_output.gbnf
+schemas/persona_blueprint.schema.json
+schemas/turn_output.schema.json
+schemas/world_blueprint.schema.json
+simula/__init__.py
+simula/__main__.py
+simula/backends.py
+simula/loop.py
+simula/py.typed
+simula/workspace.py
+simula.egg-info/PKG-INFO
+simula.egg-info/SOURCES.txt
+simula.egg-info/dependency_links.txt
+simula.egg-info/entry_points.txt
+simula.egg-info/requires.txt
+simula.egg-info/top_level.txt

simula-0.1.0/simula.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

simula-0.1.0/simula.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+simula = simula.__main__:main

simula-0.1.0/simula.egg-info/requires.txt

@@ -0,0 +1,7 @@
+platformdirs>=4.0
+
+[embeddings]
+sentence-transformers>=2.2
+
+[openai]
+requests>=2.28

simula-0.1.0/simula.egg-info/top_level.txt

@@ -0,0 +1 @@
+simula

simula-0.1.0/simula.toml.example

@@ -0,0 +1,44 @@
+# simula.toml.example
+# Copy to your workspace as simula.toml and edit.
+# Local-first, but always able to run against any OpenAI-compatible endpoint.
+
+[backend]
+# "llamacpp" (default, local) | "openai_compat"
+kind = "llamacpp"
+
+[backend.llamacpp]
+endpoint = "http://127.0.0.1:18083"
+# llama.cpp serves an OpenAI-compatible /v1/chat/completions AND native /completion.
+# Native /completion is preferred because it accepts a GBNF `grammar` for hard-constrained output.
+model = "gemma-4-12b-it"          # alias only; the loaded GGUF is what matters
+prefer_native_grammar = true
+
+[backend.openai_compat]
+# Used when backend.kind = "openai_compat". Works with OpenAI, or any compatible server.
+base_url = "https://api.openai.com/v1"
+api_key_env = "OPENAI_API_KEY"    # read from environment, never store the key here
+model = "gpt-4o-mini"
+# Structured output strategy for this backend: "json_schema" | "tools" | "repair"
+structured_output = "json_schema"
+
+[embeddings]
+# Embeddings stay local by default to avoid coupling, even in openai_compat mode.
+kind = "local_e5"                  # intfloat/multilingual-e5-small
+# kind = "openai_compat"           # alternatively, use the remote endpoint above
+
+[generation]
+temperature = 0.2                  # low for consistency; tune via eval rig
+max_tokens = 800
+
+[experience]
+# "world" | "persona"
+mode = "world"
+blueprint = "blueprints/kipple.world.json"
+
+[rag]
+top_k = 6
+hybrid = true                      # sqlite-vec (dense) + FTS5 (lexical)
+
+[workspace]
+# Leave empty to use the platform default (~/simulacra-workspace via platformdirs).
+path = ""