simula 0.1.0__py3-none-any.whl

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/__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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+simula/__init__.py,sha256=kzT6Q3-BBVJOsnQObJZdh0cGxUMrz4IWyYQ81N664Eo,599
+simula/__main__.py,sha256=xUPAHYMVcbs8v4pMoXs-TDhCe0r3tnadnYIA5irHEAk,1298
+simula/backends.py,sha256=N5kNKtex6cbbff0HOEsPQQhgnoWXEApRDFnWGNrX3G4,4554
+simula/loop.py,sha256=B67WGQpV7PhDtizpyq4OXPR6W5X1hQRqwGflTs34KGc,2948
+simula/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+simula/workspace.py,sha256=_9_9HLmuLo662AGEb5DFzVJTeHzMYKpov6v27arp1iM,1170
+simula-0.1.0.dist-info/licenses/LICENSE,sha256=_RGI15CryF1YN2o9Ridxi3SUssmvCZN7uQSp2OhquvQ,1069
+simula-0.1.0.dist-info/METADATA,sha256=klHIT8NSVfZIIEf4fdHhPpA2qGEFC_FkVsGN5vyv3vQ,3003
+simula-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+simula-0.1.0.dist-info/entry_points.txt,sha256=Z38eQwHhgp4M_p8JKVQOiycl0Hxi2vShYpMnJGMQTAU,48
+simula-0.1.0.dist-info/top_level.txt,sha256=mUmhwzusBASbf93Em7gngQaWRuqwUEN94c00KZL65JI,7
+simula-0.1.0.dist-info/RECORD,,

simula-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

simula-0.1.0.dist-info/entry_points.txt

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

simula-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

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