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).
