MARVIS-Agent: a local-first credit risk workbench that pauses for human confirmation

The problem MARVIS-Agent targets: risk work scattered across notebooks and screenshots

Credit risk development tends to produce a trail of disconnected artifacts. A requirements note lives in one place, a feature script in another, a model notebook somewhere else, and the final report is a document that no longer points back at the run that produced it. The README frames this directly: requirements, scripts, notebooks, screenshots and reports live in different places, and analysts manually reconnect the data, feature, model, strategy and report steps. The stated consequence is that an AI can explain an answer but it is hard to prove where a number came from. MARVIS-Agent is aimed at that gap. It is a local-first platform that keeps the request, the plan, the execution evidence, the decisions and the deliverables inside a single task. The intended user is a risk analyst, model developer or validator who works with CSV or Excel files on a controlled machine, not a data platform team building a hosted service. The README is explicit that this is not a chatbot wrapped around a collection of scripts, and the architecture it describes supports that claim: the agent's role is to clarify, plan and route, while the numbers come from platform code.

Plan, gate, execute: the mechanism behind the agent loop

The README gives a flow diagram with seven stages: describe the risk goal, the agent clarifies inputs and definitions, a validated workflow plan is produced, human confirmation happens where required, deterministic tools execute, evidence and artifacts and reports come out, and the result is reviewed and iterated. Two design decisions stand out. The first is the responsibility gate. High-impact actions pause for confirmation rather than running through, which means the agent cannot silently rewrite a sample definition or push a strategy rule change without a human step in between. The second is the separation between the language layer and the calculation layer. KS, AUC, PSI, bad rate, approval rate, profit and impact are described as calculated by deterministic platform code, not guessed by an LLM. That distinction is the whole argument for using an agent here at all: the model handles intent and orchestration, and the scoring kernels stay conventional. The README also states that Agent mode and the Manual Workbench share the same validated workflows, tools, schemas and deterministic calculation kernels. If that holds in the code, it means a result produced through the conversational path and a result produced by hand should be comparable, because they run the same underlying operations. I cannot verify that from the README alone, and it is one of the first things I would check in the repository.

The seven-step strategy workflow and the governed data-to-model path

MARVIS-Agent ships two long pipelines rather than a single feature. The strategy workflow is described as seven steps covering current and historical evidence, governed dual-population samples, univariate and model evidence, trees, Cross, scorecards, Voting, Strategy Pools, impact measurement, validation, code delivery, and four-format review reports. The data-to-model workflow covers file ingest and join, feature analysis and engineering, training and comparison of multiple recipes, PMML export for supported recipes, scoring, model reports, and a handoff of the selected model plus supporting evidence into model validation. The phrase supported recipes matters: the README does not claim PMML export is universal across every model type, and it repeats the qualifier in the module table. Around these pipelines sit supporting modules. Data processing registers CSV and Excel files, infers schemas, profiles data, proposes joins, and diagnoses match rate, fan-out and row inflation before deduplicating explicitly. Labels and features cover bad-label definition from DPD plus observation and performance windows, cohort maturity checks, development/validation/OOT sample design, and IV, KS, AUC, PSI, Lift and Coverage calculations. Validation scans Notebook, sample, PMML and dictionary materials, executes the Notebook, and compares in-memory model scores against submitted PMML scores. There is also a batch entry that runs one to ten isolated validation tasks sequentially, preserves every individual report, and adds a batch summary workbook. That batch design is a deliberate trade-off: sequential isolation costs wall-clock time but keeps each task's evidence separate.

Getting it running: what the README does and does not give you

This is where the material thins out. The README states Python 3.11 to 3.13 via a badge, and the repository layout includes a marvis directory (the logo path is marvis/static/brand/marvis-workspace-logo.png) plus a docs/readme-assets/screenshots directory. There is a CI workflow at .github/workflows/ci.yml, referenced by the CI status badge for the main branch. A tags badge points at github.com/eddyzzl/marvis-risk-agent/tags, but the supplied metadata shows no releases retrieved, so I cannot give you a version number to pin or a pip install line, because none appears in the material I have. The same applies to environment variables, config keys and CLI entry points: the README excerpt does not include them. What I can say concretely is that the licence is MIT, declared both in the badge and in the repository metadata, and that the project is not archived and was last pushed on 2026-08-28. If you are evaluating this for a team, the practical first step is to read the repository's own installation section rather than trusting a summary, and to check whether the CI badge on main is green before you spend time on a local setup. I am not going to invent a requirements file, a Docker image or a service port that the material does not show.

Where the design creates friction, and when this is the wrong tool

The local-first choice has a cost. Files, task state, evidence and outputs stay in a controlled local workspace by default, which is good for data governance and awkward for collaboration. There is no described server component, no multi-user task queue, and no shared artifact store, so two analysts working the same portfolio will not see each other's runs unless they arrange it themselves. The human confirmation gates are a second source of friction: they are the right default for credit risk, but they mean the agent cannot be left to complete a long pipeline unattended, and any workflow that depends on overnight batch autonomy will fight the design. Third, the deterministic-kernel claim is only as good as its coverage. The README lists specific metrics (KS, AUC, PSI, bad rate, approval rate, profit, impact) as platform-computed, but it does not enumerate every calculation in the strategy workflow, and the PMML qualifier shows the project is willing to scope features rather than promise them everywhere. If your workflow depends on a model family outside the supported recipe set, the handoff into validation may not be as clean as the module table suggests. Finally, the absence of published releases is a real adoption constraint. Without tags you have no version boundary, so an upgrade is a pull of main rather than a controlled version bump, and you carry the cost of reviewing whatever changed.

How it differs from a notebook-and-library stack

The obvious alternative is the conventional combination of pandas, scikit-learn or statsmodels, and a Jupyter notebook, with a scoring library such as scorecardpy or optbinning for the credit-specific pieces. That stack is more flexible and has a much larger user base, and it has no opinion about how you organize a task. The difference in approach is not the algorithms. It is where the state lives. In a notebook stack, the plan, the parameters, the intermediate frames and the final numbers exist only as long as the kernel session and the saved file, and the lineage is whatever the analyst wrote down. MARVIS-Agent instead treats the task as the unit: the request, plan, execution evidence, decisions and deliverables stay together, and governed workflows carry task ownership, data fingerprints, parameters and artifacts forward. The README's comparison table makes the same point about reports, which are generated from structured, versioned platform results rather than copied into a document that loses its lineage. The trade is explicit. You give up the freedom to write arbitrary Python in the middle of a run, and in exchange you get a record of what ran and on which data. For a team that has to answer a validator's question six months later, that exchange is often worth making. For a research group exploring a new modelling idea, it usually is not.

Licence, maintenance and what to verify before you commit

The project is MIT-licensed, which is permissive and places few obligations beyond retaining the copyright and permission notice in copies or substantial portions. That is a statement about the licence text, not legal advice, and if you redistribute MARVIS-Agent inside a commercial product you should read the LICENSE file and your own policy rather than relying on a summary. On maintenance, the metadata shows an active repository: not archived, last push on 2026-08-28, and a CI workflow configured on main. What it does not show is a release history, so there is no changelog to read and no deprecation policy to plan against. The Python version range of 3.11 to 3.13 is narrow enough that an upgrade of your interpreter could take you outside the supported set, and that is worth checking before you standardize on it. The upgrade cost is therefore mostly review time: because you are tracking main, every pull is a code review of an unknown diff. My concrete suggestion is to fork the repository, pin your fork at a commit you have reviewed, and re-read the workflow definitions under the marvis directory whenever you rebase. If you need a vendor-supported product with a support contract, this is not that, and the README does not claim otherwise.

Editorial conclusion

Adopt MARVIS-Agent if you are a credit risk team that already keeps data on local disks and wants the plan, evidence and deliverables to stay inside one governed task, and if you can accept a Python 3.11 to 3.13 deployment with no published release artifacts to pin. Do not adopt it if you need a hosted multi-tenant service or a stable tagged version today. First verify the CI workflow on the main branch actually passes, confirm which recipes support PMML export, and check the LICENSE file text against your own redistribution policy.

Official sources

1. eddyzzl/marvis-risk-agent on GitHub
2. Issues
3. License: MIT
4. README