Oransim simulates marketing decisions instead of reporting what already happened

An engine, not a dashboard, and the data is the commercial part

The project positions itself as a causal digital twin for marketing, and the structure of the offer is unusual enough to be worth stating plainly.

The tagline is that you can audit the engine and license the data. The readme says the repository you are reading is the same causal engine running on a 21 thousand note demo corpus, and that you can try it, audit the mechanism end to end, and then explore the live enterprise data panel or contact the company for licensed access.

So the open source part is the mechanism, and the commercially valuable part is the data corpus behind it. For the licensed offering the readme lists 4.3 million and more indexed notes, 2.1 million and more creators across 15 verticals, and a surveyed consumer panel of more than 100 thousand, refreshed daily through licensed platform APIs.

The company behind it is OranAI Ltd, a Shenzhen based AI marketing company founded in May 2024, with a multi million dollar angel round, in house multimodal models named Oran-VL 7B and Oran-XVL 72B, four products including the creative agent PhotoG and the insight engine DataG, and more than 70 enterprise clients.

Oransim itself is the causal engine inside that stack. The readme is specific about what lives in the repository: the do() operator, the per-arm counterfactual heads and the 14 day Hawkes rollout that answer a what if question about swapping one KOL for another on day three of a campaign. It was open sourced under Apache-2.0 so buyers can audit the reasoning.

The implementation is Python, the version is 0.2.0a0 and the package is classified as Development Status 3 - Alpha.

Three campaign decisions, one engine

The What it solves section frames the product as three questions that traditional tools break on.

The first is pre-launch. The question is: you have 4 creative videos, 3 KOL shortlists and 2 budget tiers, which combination has the highest ROI? The traditional approach is an A/B test for two weeks, burning 500 thousand yuan to learn. Oransim is a 60 second simulation on zero, ranking all 24 combinations with P35 and P65 confidence bands, and you pick the top 3 to actually test.

The second is mid-campaign. Day 3 CTR is below target, can you swap two KOLs and reallocate budget to three others, and how much does the ROI shift? The traditional approach is a data team rebuilding a dashboard overnight. Oransim answers with a do(kol=swap_A_for_B, day=3) counterfactual rollout in 30 seconds, showing the 14 day path difference with the intervention applied.

The third is post-mortem. The campaign underperformed, what if we had spent on one platform instead of another? The traditional approach is retrospective analysis with an ambiguous conclusion. Oransim loads the actuals, applies do(platform_alloc={xhs: 1.0}), and returns the counterfactual ROI curve over the same agent population.

The value of putting all three on one engine is the point of the section, and the practical benefit is that a pre-launch ranking and a mid-campaign intervention use the same model, so the ranking is not a different model from the one you later steer with.

Why a mix model, a CDP and a black box each fail differently

There is a table in the readme that maps the three questions onto the existing categories of tool, and it is a compact statement of the project's argument.

For pre-launch ROI ranking across the creative, KOL and budget combinations, the existing tool is a classical marketing mix modeller, which fits the total revenue curve and gives one number per period. What is missing is the ability to say which combination, because an MMM is a total, not a per-arm counterfactual.

For the mid-campaign intervention, the existing tool is a customer data platform, which reports what already happened, click funnel and cohort retention. What is missing is the ability to roll forward under a do(), because a DMP is observational, not causal.

For the post-mortem counterfactual, the existing tool is a black box predictor such as AutoML or an LLM asked to predict ROI, which outputs a number with no derivation. What is missing is the ability to audit the reasoning, because SHAP plots are not a causal graph.

That last distinction is the sharpest one in the table, and it is the one that decides whether a marketing team will accept a prediction at all. A number with an explanation attached is not the same as a number you can interrogate, and a SHAP feature importance tells you which input moved the output, not which assumption would have to change for the output to change.

The mechanism: a causal graph, a do operator and a million simulated consumers

The section titled Why you can trust it opens with the auditability claim, and the mechanism is described in specific terms.

The repository is the full causal engine rather than a marketing demo, and you can clone it, run it on your scenarios and trace any prediction back through the 64 node causal graph to which agent decision and which budget curve calculation produced it. The readme's framing is that there is no trust us, it is ML, every prediction is decomposable.

The simulated population is the other half. The licensed data panel runs a counterfactual reasoning engine on a virtual consumer society of more than one million, with LLM backed soul personas reading your actual creatives. The open source repository runs the same engine on the smaller demo corpus.

So the architecture has three parts. The causal graph is the model of the campaign, the society is the population the interventions are rolled out against, and the LLM personas are what makes the agents react to the creative rather than to a number.

The rollout is a 14 day Hawkes process, which is the self reinforcing nature of social spread modelled explicitly, and the per-arm counterfactual heads are how a single do() produces a distribution rather than a single figure, which is where the P35 and P65 bands come from.

Running the engine yourself

The quick start is a clone and an editable install, and the readme shows it in one block.

git clone https://github.com/OranAi-Ltd/oransim.git && cd oransim
pip install -e '.[dev]'

The server is then started with an ASGI application served by uvicorn, and the readme points at the module for the API entry point.

The dependency list in the project file explains what the engine is made of. fastapi and uvicorn for the API, numpy and scipy for the numerical work, scikit-learn and lightgbm for the budget curve models, and pydantic for the schemas that make the counterfactual requests typed.

The last dependency has a comment attached to it that is worth reading, because it is a good example of a dependency that looks optional and is not. jieba, the Chinese word segmentation library, is marked as required, not soft, and the comment explains that without it the tag extraction falls back to hashtags only, which produces empty tag pools on the synthetic notes corpus and breaks the tag lift computation. A Chinese marketing tool that segments Chinese text cannot treat that as an optional extra.

The optional research extra is the other half of the stack, with torch, pandas, matplotlib, pyarrow, openpyxl, pytest and an uplift library, which is the set of tools you need for the experiments rather than for the service.

The environment template and the LLM provider layer

The .env.example file is the clearest document of what the engine needs at runtime, and its structure is good.

The first key is LLM_MODE, with the comment that mock returns deterministic stub responses with no network and is free, to be used for CI and local exploration, while api requires a real key below. So the whole system can be run, tested and audited with no LLM access at all, and that is a deliberate property for a project whose pitch is auditability.

The second is LLM_PROVIDER, which selects the native request format to speak. The list is openai, which covers OpenAI, DeepSeek, OpenRouter, vLLM or any OpenAI compatible endpoint, anthropic for the messages endpoint with the system prompt as a top level field, gemini for generateContent with systemInstruction and contents, and qwen for the DashScope native generation endpoint. The file also lists the aliases accepted for the same providers.

LLM_MODE=mock
LLM_PROVIDER=openai

After that come the shared base URL and key, with a comment listing the base URLs of the compatible providers including a local vLLM at localhost, and the model name.

The point of this design is that the LLM is a component rather than the centre of the system. The personas are generated text, the causal graph is the model, and the engine is the thing you audit. Making the provider swappable with a mock mode keeps that ordering intact.

The repository layout and the boundary of the open source part

The top level listing describes a full stack project rather than a library.

There is backend/ and frontend/, with an index.html at the root, plus models/ for the model artefacts, data/ for the corpora, experiments/ for the research scripts, examples/ for the notebooks, docs/ with an mkdocs.yml, tests/, and docker/ for the container setup. The examples are four notebooks that map onto the documentation's structure: a quickstart, a counterfactual notebook, a custom platform notebook, and one on soul agents.

The project files are the conventional ones for a company repository, with a CITATION.cff, a CHANGELOG.md, a ROADMAP.md, a SECURITY.md, a CODE_OF_CONDUCT.md, a CONTRIBUTORS.md, a NOTICE file, and a .env.example that is documented rather than merely present.

What the open source repository does not contain is the thing that makes the results meaningful in production, which is the licensed corpus of 4.3 million notes, 2.1 million creators and the surveyed panel. The readme is explicit that the repository runs on a 21 thousand note demo corpus and that the live panel is a separate product.

So the evaluation has to be two questions. Can you audit the engine, which this repository answers, and can you license the data, which is a conversation with the company. The first is what the open source part is for, and the readme is clear that it is a real answer rather than a marketing promise.

Editorial conclusion

Adopt Oransim when you need to reason about a marketing intervention before spending on it and your stakeholders will only trust a number they can trace back to a mechanism, since the project is explicit that every prediction is decomposable through its causal graph. Do not adopt it expecting the live data, because the open source repository runs on a small demo corpus and the indexed note and creator panel is licensed separately. Verify first that the demo corpus is representative enough for the decision you are testing, that the LLM persona mode you choose is the one you can afford, since real mode needs an API key and mock mode returns deterministic stubs, and that your team reads the causal graph rather than the summary output.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. OranAi-Ltd/oransim on GitHub
4. Project website
5. README