ai #gemma #opensource #hackathon

Don't just ask AI what to choose. Ask AI whether you have enough evidence to choose.

We use AI every day to help us solve problems and make decisions.

Which technology should we use?

Should we change our database?

Which cloud platform fits our requirements?

Are we choosing the right vendor?

Should we build a solution ourselves or use an existing one?

Modern AI assistants can answer these questions in seconds. Their answers may sound logical and convincing, but there is an important problem: a confident recommendation does not necessarily mean we have enough evidence to make the right decision.

What if AI could do something more useful than simply recommending an option?

What if it could identify our assumptions, highlight missing information, evaluate risks, and help us understand whether we are actually ready to make that decision?

That question inspired us to build DecisionShield, an AI-powered Decision Readiness and Risk Audit Platform.

We developed this project with our team, Wakie Wakie, during the Hacktoberfest Hack Day Coimbatore, organized by INIT Club and IDEA Club.

This article explains the problem, our approach, the architecture, the technologies we used, and what makes DecisionShield different from a conventional AI chatbot.

🔗 Project Links

🤔 The Problem: AI Can Answer Before We Are Ready

Imagine asking an AI assistant:

Should our startup migrate from PostgreSQL to MongoDB?

A typical AI assistant might explain that MongoDB offers a flexible document model and can support horizontal scaling.

That response might be reasonable, depending on the application's requirements.

But before making the decision, we should ask a few more questions.

• What do our database query patterns look like?
• How important are transactions and data consistency?
• Does our application depend on complex relational queries?
• How much downtime can we tolerate during migration?
• What will the total infrastructure cost be over the next three years?
• Does our engineering team have experience with the new database?
• What risks could arise during migration?

Without this information, choosing a database based on a general recommendation could introduce unnecessary complexity, unexpected costs, or operational problems.

The issue is not that AI cannot provide useful answers.

The issue is that AI may provide an answer even when important information is missing.

DecisionShield is designed to address this gap by examining the decision and the evidence behind it before presenting a readiness assessment.

💡 Our Idea: What Is DecisionShield?

DecisionShield is an AI-powered Decision Readiness and Risk Audit Platform.

Instead of immediately selecting an option for the user, it analyzes the decision context and identifies the information that supports or weakens the decision.

The platform organizes its analysis into several categories:

• ✅ Facts: Information supported by the provided context.
• ⚠️ Assumptions: Statements that have not been sufficiently verified.
• ❓ Unknowns: Important information that is currently unavailable.
• 📌 Claims: Statements that require further verification.
• 🚨 Risks: Potential problems that could affect the outcome.
• 🔍 Missing Evidence: Information needed to evaluate the decision more confidently.
• 🧪 Stress-Test Scenarios: Hypothetical changes that could affect decision readiness.

The structured analysis is then passed to a deterministic decision engine, which calculates a Decision Readiness Score.

For example, an assessment might look like this:

Decision Readiness: 64/100 — NOT READY

The system could identify three critical pieces of missing evidence that should be investigated before the decision is finalized.

This is an illustrative example of the intended assessment workflow, not a guarantee that every decision will receive the same result.

The important difference is that DecisionShield does not simply tell users what to choose. It helps them understand what they need to investigate before choosing.

🔄 How DecisionShield Works

The platform follows a structured pipeline that combines AI reasoning with deterministic scoring.

                USER DECISION
                     |
                     v
              Decision Context
                     |
                     v
               Gemma 4 E4B
              Semantic Reasoning
                     |
                     v
           Structured AI Analysis
                     |
          +----------+----------+
          |          |          |
          v          v          v
        Facts    Assumptions   Risks
          |          |          |
          +----------+----------+
                     |
                     v
              Missing Evidence
                     |
                     v
             Structured JSON
                     |
                     v
             Pydantic Validation
                     |
                     v
          Deterministic Decision Engine
                     |
                     v
           Decision Readiness Score
                     |
                     v
                Stress Testing
                     |
                     v
              Decision Stability
                     |
                     v
                Decision Audit

The workflow separates language-model analysis from numerical evaluation.

Gemma processes the decision context and generates structured findings. The backend validates the resulting data and passes it to the decision engine.

This separation helps make the scoring process more consistent, testable, and easier to inspect.

🧠 Why Not Build Another AI Chatbot?

One of our central design decisions was to go beyond a simple question-and-answer interface.

A conventional AI assistant typically follows this pattern:

User Question
     |
     v
    LLM
     |
     v
Text Recommendation

DecisionShield follows a more structured process:

Decision Context
       |
       v
Evidence Extraction
       |
       v
Information Classification
       |
       v
Risk Analysis
       |
       v
Missing Evidence Detection
       |
       v
Deterministic Scoring
       |
       v
Stress Testing
       |
       v
Decision Audit Report

The difference is the focus of the analysis.

A chatbot primarily responds to the question.

DecisionShield examines the quality and completeness of the information behind the decision.

It is not intended to replace human judgment. Instead, it aims to give decision-makers a clearer understanding of the available evidence, possible risks, and unresolved questions.

🧩 Core Features

1. Decision Workspace

The Decision Workspace is where users define the decision they want to evaluate.

Users can provide:

• Decision title
• Decision description
• Available options
• Background context
• Requirements
• Constraints
• Existing evidence

For example:

Decision: Should our startup migrate from PostgreSQL to MongoDB?

Options:

• Continue using PostgreSQL.
• Migrate to MongoDB.

Context:

Our startup currently stores approximately 2 TB of data and expects significant growth over the next three years.

Constraints:

• Small engineering team.
• Limited migration budget.
• Need to minimize operational disruption.

Providing context and constraints helps the system analyze the decision against the situation described by the user rather than treating the question in isolation.

2. AI-Powered Evidence Analysis

DecisionShield uses Gemma 4 as its semantic reasoning layer.

The model analyzes the supplied context and separates the information into categories that support the remaining workflow.

Facts

Facts are statements directly supported by the supplied context.

For our database example:

• PostgreSQL is the current database.
• The existing data volume is approximately 2 TB.
• The team expects future growth.

Assumptions

Assumptions are statements that may be true but have not been sufficiently established.

Examples:

• MongoDB will automatically solve our scalability challenges.
• Switching databases will reduce operational complexity.
• Migration will reduce long-term costs.

These statements require investigation rather than automatic acceptance.

Unknowns

Unknowns are important details that have not been supplied.

Examples:

• Query workload patterns.
• Transaction requirements.
• Data consistency requirements.
• Expected peak traffic.
• Acceptable migration downtime.

Claims

Claims are statements that require verification before they can be relied upon.

For example:

"MongoDB will be cheaper over the next three years."

The system identifies such claims as items requiring supporting evidence.

The resulting classification provides the foundation for identifying risks and evaluating decision readiness.

3. Decision Readiness Score

DecisionShield calculates a score on a scale of 0 to 100.

The scoring process can consider dimensions such as:

• Evidence quality.
• Requirement coverage.
• Evidence completeness.
• Risk coverage.
• Assumption load.
• Unknown information.
• Decision stability.

A key architectural principle is that Gemma does not directly generate the final numerical score.

Instead, the workflow is:

Gemma 4
   |
   v
Semantic Analysis
   |
   v
Structured JSON
   |
   v
Pydantic Validation
   |
   v
Python Decision Engine
   |
   v
Readiness Score

The language model is responsible for semantic analysis, while the backend handles validation and scoring.

For example, an illustrative report could contain:

        DECISION READINESS

              64 / 100

             NOT READY

Evidence Quality        72%
Requirement Coverage    80%
Risk Coverage           55%
Evidence Completeness   61%
Decision Stability      68%

These numbers are illustrative rather than universal thresholds or a claim that every category directly maps to the overall score.

The goal is to provide a structured assessment that helps users identify areas requiring further investigation.

4. Missing Evidence Detection

One of the most useful questions DecisionShield asks is:

What information are we missing that could materially change this decision?

For the PostgreSQL-to-MongoDB example, the platform might identify the following priorities.

Critical information to investigate

1. Current query workload and query performance.
2. Transaction and consistency requirements.
3. Expected peak traffic and workload characteristics.

Other important information

1. Migration downtime tolerance.
2. Infrastructure and maintenance costs over three years.
3. Team experience with the target database.

The workflow goes beyond listing unknowns.

It can also identify verification actions that help users investigate them.

For example:

Missing evidence: Expected peak traffic.

Suggested verification action: Measure current peak requests per second, examine traffic patterns, and estimate expected workload growth over the next three years.

This turns an abstract concern into a practical next step.

5. Risk Analysis

A decision can appear reasonable under normal conditions but still introduce significant risks.

DecisionShield identifies potential risks associated with the supplied decision context.

Risk information can include:

• Severity.
• Likelihood.
• Impact.
• Confidence.
• Supporting evidence.

Consider the database migration example.

Potential risk: Complex relational workloads

If the application relies heavily on relational joins and complex queries, moving to a document-oriented database may require substantial data-model and application changes.

Other possible risks include:

• Migration downtime.
• Unexpected infrastructure costs.
• Team learning curve.
• Application compatibility issues.
• Data consistency challenges.

The backend incorporates risk-related information into the readiness assessment according to the implemented scoring logic.

These findings should be treated as potential risks to investigate, not proof that a particular database is unsuitable.

6. Decision Stress Testing

A decision that appears reasonable today may become less suitable when its assumptions change.

DecisionShield includes a stress-testing concept to examine how hypothetical scenarios can affect the decision assessment.

Example scenarios include:

Scenario 1: Traffic increases by 10×

Would the proposed architecture continue to satisfy performance and availability requirements?

Scenario 2: Infrastructure budget decreases by 50%

Would the decision remain financially practical?

Scenario 3: New data residency requirements are introduced

Would the proposed solution meet the updated compliance constraints?

Scenario 4: The engineering team loses its existing database expertise

Would the team still be able to maintain and troubleshoot the system effectively?

Scenario 5: Data volume doubles

Would the current assumptions about storage, performance, and cost remain reasonable?

These scenarios allow users to explore how changing conditions could affect their decision.

📉 Understanding Decision Stability

Suppose a hypothetical decision has an initial readiness score of 72/100.

Stress testing might produce the following illustrative results:

The large reduction under the new compliance scenario suggests that the decision may be sensitive to changing requirements.

The system can use such comparisons to highlight decision stability concerns.

A high initial score does not automatically mean a decision will remain suitable under every possible condition.

Note: These figures are illustrative examples, not measured benchmark results.

🧠 Why Gemma 4?

DecisionShield uses Gemma 4 E4B as its semantic reasoning layer rather than treating the model as a generic chatbot.

The model's role is to analyze unstructured decision context and help produce structured findings.

The process can be represented as:

Unstructured Decision Context
             |
             v
        Gemma 4 E4B
             |
             v
       Semantic Analysis
             |
      +------+------+------+
      |      |      |      |
      v      v      v      v
    Facts Assumptions Risks Unknowns
             |
             v
      Claims and Missing
           Evidence
             |
             v
       Structured Output

The backend then validates and processes the structured output to generate measurable decision metrics.

Separation of Responsibilities

This division of responsibilities is important because language-model analysis and numerical calculations serve different purposes.

The model interprets context. The backend validates the data and performs the scoring. The human remains responsible for the final decision.

⚙️ Technical Architecture

DecisionShield uses a frontend-backend architecture with separate AI analysis and scoring responsibilities.

                 +----------------------+
                 |    React + Vite UI   |
                 |                      |
                 | Decision Workspace   |
                 | Dashboard            |
                 | Evidence Explorer    |
                 | Stress Testing       |
                 | Audit Report         |
                 +----------+-----------+
                            |
                         REST API
                            |
                            v
                 +----------------------+
                 |       FastAPI        |
                 |       Backend        |
                 +----------+-----------+
                            |
                 +----------+-----------+
                 |                      |
                 v                      v
       +------------------+  +-------------------+
       |   Gemma 4 E4B    |  | Decision Engine   |
       |                  |  |                   |
       | AI Reasoning     |  | Deterministic     |
       | Classification   |  | Scoring           |
       | Risk Discovery   |  | Stability Analysis|
       +--------+---------+  +---------+---------+
                |                      |
                +----------+-----------+
                           |
                           v
                 +----------------------+
                 | Structured Decision  |
                 | Analysis Result      |
                 +----------+-----------+
                            |
                            v
                 +----------------------+
                 |   Decision Audit     |
                 |       Report         |
                 +----------------------+

The frontend communicates with the backend through REST APIs.

The backend coordinates the analysis workflow, validates structured data, and calculates the readiness assessment.

The resulting analysis is presented through the user interface as a decision audit.

🛠️ Technology Stack

Frontend

• React
• Vite
• Tailwind CSS
• Recharts
• Framer Motion

Backend

• Python
• FastAPI
• Pydantic
• Uvicorn

AI

• Gemma 4 E4B
• 4-bit quantization
• Local inference

Architecture

• REST API.
• Structured JSON.
• Deterministic scoring engine.
• In-memory decision storage for the MVP.
• AI provider and demo-provider fallback workflow.

The technology choices support a modular architecture in which the user interface, AI analysis, validation, and scoring logic have distinct responsibilities.

💻 Running DecisionShield Locally

The following steps describe the setup documented for the project. Depending on your environment and model configuration, additional setup may be necessary.

Prerequisites

You will need:

• Python 3.x.
• Node.js and npm.
• Git.
• An NVIDIA GPU is recommended for local Gemma inference.
• Approximately 16 GB of RAM.
• Approximately 6 GB of VRAM for the target E4B 4-bit configuration.

Actual memory requirements depend on the model implementation, quantization format, runtime, and inference settings.

1. Clone the Repository

git clone https://github.com/Praveen-Raj-Thulasi/DecisionAI/
cd DecisionShield

Make sure the directory name matches the actual folder created by your clone operation.

2. Set Up the Backend

cd backend
python -m venv .venv

On Windows:

.venv\Scripts\activate

On Linux or macOS:

source .venv/bin/activate

Install the backend dependencies:

pip install -r requirements.txt

3. Configure the Environment

Create the environment configuration file using the supplied example:

cp .env.example .env

On Windows, you can copy the file using your preferred terminal or file explorer.

Configure the required settings, including the model path and other environment-specific values.

4. Start the Backend

uvicorn app.main:app --reload

Run the command from the backend directory.

5. Start the Frontend

Open another terminal:

cd frontend
npm install
npm run dev

Open the local address printed by Vite in your terminal.

For exact dependency requirements and configuration options, refer to the repository's README and environment example.

🧪 Demo Scenario: PostgreSQL vs MongoDB

For a simple demonstration, consider this decision:

Should our startup migrate from PostgreSQL to MongoDB?

The user provides context about current data volume, expected growth, team size, and operational constraints.

DecisionShield then follows the analysis workflow:

Decision Input
      |
      v
Facts
      |
      v
Assumptions
      |
      v
Unknowns
      |
      v
Risks
      |
      v
Missing Evidence
      |
      v
Readiness Assessment
      |
      v
Stress Testing
      |
      v
Decision Stability
      |
      v
Final Decision Audit

For example, the system might identify that the team expects rapid growth but has not supplied sufficient information about query workloads, transaction requirements, or long-term infrastructure costs.

Instead of assuming that a migration is necessary, the platform highlights what should be investigated.

That is the central idea behind DecisionShield: a decision should be evaluated using the available evidence and the risks that remain unresolved.

🔬 Example Analysis

Let's examine a sample decision context.

Input

Our startup currently has approximately 2 TB of PostgreSQL data.

We expect rapid growth and believe MongoDB will make scaling easier.

Our engineering team is small, and we want to reduce operational complexity.

Facts

• PostgreSQL is the current database.
• The data volume is approximately 2 TB.
• The team expects significant growth.
• The team wants to reduce operational complexity.

Assumptions

• MongoDB will automatically improve scalability.
• Migrating will reduce operational complexity.
• The new database will be cheaper over the long term.

Unknowns

• Query patterns.
• Transaction requirements.
• Consistency requirements.
• Peak workload.
• Migration downtime tolerance.

Potential Risks

• Additional complexity for relational workloads.
• Migration-related downtime.
• Learning curve for the engineering team.
• Unanticipated infrastructure costs.

Missing Evidence

• Query workload analysis.
• Transaction and consistency requirements.
• Three-year cost comparison.
• Expected peak traffic.
• Migration and rollback strategy.

Illustrative Result

Decision Readiness: 64 / 100

Status: NOT READY

Recommended next step:
Investigate the critical missing evidence
before finalizing the migration decision.

The score and status above are examples used to explain the concept, not an independently verified assessment of an actual production decision.

The purpose of this analysis is not to claim that PostgreSQL or MongoDB is universally better. It is to identify the evidence needed to determine which option best fits the application's requirements.

🏗️ Project Structure

The documented project structure follows a frontend-backend separation.

DecisionShield/
|
+-- frontend/
|   +-- components/
|   +-- pages/
|   +-- services/
|   +-- ...
|
+-- backend/
|   +-- app/
|   |   +-- api/
|   |   +-- ai/
|   |   +-- engine/
|   |   +-- schemas/
|   |   +-- services/
|   |   +-- ...
|   |
|   +-- tests/
|   +-- requirements.txt
|
+-- docs/
|
+-- README.md

The frontend contains the interface and visualization components.

The backend separates API handling, AI integration, schemas, scoring logic, and supporting services. This structure helps keep the system modular and makes individual components easier to test and maintain.

🔐 Reliability by Design

One important design principle is the separation between AI-generated analysis and numerical decision logic.

We do not want the model to simply return an unsupported statement such as:

Gemma:
"I think the decision readiness is 87."

Instead, the intended workflow is:

Gemma
  |
  v
Facts / Assumptions / Risks / Unknowns
  |
  v
Structured JSON
  |
  v
Pydantic Validation
  |
  v
Python Decision Engine
  |
  v
Readiness Score

This makes it easier to validate the structure of the analysis, inspect the scoring process, and test the backend independently of the model.

However, deterministic calculations do not automatically guarantee that the final result is correct. The quality of the assessment still depends on the supplied evidence, the classification, and the scoring rules.

🧪 Demo Mode and AI Fallback

Local AI inference can introduce practical challenges during development and hackathons.

These may include:

• Model loading failures.
• GPU memory limitations.
• CUDA or runtime configuration issues.
• Inference errors.
• Environment setup problems.

DecisionShield includes a fallback/demo-provider approach intended to keep the application demonstrable when local model inference is unavailable.

The documented flow is:

                AI Analysis
                     |
             +-------+-------+
             |               |
             v               v
          Gemma 4        Demo Provider
             |               |
             +-------+-------+
                     |
                     v
             Structured Output
                     |
                     v
             Decision Engine
                     |
                     v
             Audit Report

Both providers are designed to feed the same downstream processing workflow through a common structured-output format.

The application distinguishes whether an analysis comes from the actual AI provider or demo mode. This distinction matters because demonstration output should not be mistaken for a live model-generated analysis.

🌍 Why DecisionShield Could Matter

Making decisions is not only about collecting more information.

It is also about understanding the quality and limitations of the information we already have.

Before committing to a decision, it is useful to know:

• Which facts support the decision?
• Which assumptions still need testing?
• What important information is missing?
• Which risks could affect the outcome?
• What would happen if the original constraints changed?

DecisionShield aims to turn these questions into a repeatable decision-review workflow.

Rather than presenting AI as the final authority, the platform treats it as a tool for examining the reasoning and evidence behind a decision.

The objective is simple:

AI should help people make better-informed decisions, not encourage them to follow recommendations blindly.

🚀 Future Roadmap

DecisionShield is an MVP, and several enhancements could make the platform more useful.

📄 1. Evidence Ingestion

Allow users to upload documents, PDFs, spreadsheets, and reports.

The system could extract relevant information and use it as supporting evidence for a decision assessment.

🔗 2. Evidence Provenance

Track where each fact originated.

For example:

Fact
 |
 v
Source Document
 |
 v
Page or Section
 |
 v
Supporting Evidence

This would help users inspect the source behind important findings rather than relying only on generated summaries.

🧠 3. Advanced Decision Graphs

Represent relationships between evidence, assumptions, risks, requirements, and decisions.

Evidence
   |
   v
Assumption
   |
   v
Risk
   |
   v
Requirement
   |
   v
Decision

A decision graph could make it easier to understand how one unresolved assumption affects multiple parts of an assessment.

👥 4. Collaborative Decision Rooms

Allow teams to evaluate decisions together, contribute evidence, discuss risks, and compare assessments.

📚 5. Decision History

Maintain a history of decisions and their assessments so users can understand how a decision changes as new evidence becomes available.

🌐 6. External Knowledge Verification

Integrate trusted external sources to help users investigate missing evidence and verify important claims.

🧪 7. Advanced Stress Testing

Expand scenario analysis to explore more complex constraints and evaluate how sensitive a decision is to changes in assumptions.

🏢 8. Domain-Specific Audits

Introduce specialized decision templates for areas such as:

• Software architecture.
• Cloud infrastructure.
• Procurement.
• Hiring.
• Business strategy.
• Product planning.

These are potential future improvements, not claims that all these capabilities are already implemented.

⚠️ Limitations

DecisionShield is intended to support decision-making, not guarantee a correct outcome.

There are several limitations to consider:

• AI-generated classifications may be imperfect.
• Missing-evidence suggestions may not cover every important factor.
• Results depend on the quality and completeness of the supplied context.
• Stress-test scenarios are hypothetical analyses, not predictions of future events.
• A readiness score is an analytical indicator, not an objective measure of truth.
• A deterministic scoring engine can still produce misleading results if its inputs or scoring rules are inadequate.

For high-impact decisions, users should verify important claims, consult appropriate experts, and use independent evidence before acting.

🌱 Open Source and Community Contributions

DecisionShield is being developed as an open-source project.

We want the project to provide an opportunity to explore ideas around:

• Local AI inference.
• Gemma-based reasoning.
• Structured AI outputs.
• Deterministic scoring.
• Decision intelligence.
• Human-in-the-loop systems.

Developers interested in the project can explore the source code, share feedback, suggest improvements, and contribute to future development.

Repository: https://github.com/Praveen-Raj-Thulasi/DecisionAI

Please refer to the repository for available contribution instructions and current project issues.

👥 Our Team

Team Name: Wakie Wakie

Team Members & Contributions

DecisionShield was developed collaboratively during the Hacktoberfest Hack Day Coimbatore.

Working together gave us an opportunity to discuss the problem, explore technical approaches, integrate components, and learn from the challenges of building an AI-powered application.

Teamwork was an important part of the experience, and the project reflects our shared effort to explore a different approach to AI-assisted decision-making.

🏆 Hackathon Experience

Event: Hacktoberfest Hack Day Coimbatore

Organizers: INIT Club & IDEA Club

Additional Challenge: Gemma 4

Building DecisionShield during an in-person hackathon was a valuable learning experience.

Hackathons bring a different kind of challenge. There is limited time to understand a problem, design a solution, implement the main workflow, and bring different components together.

This project encouraged us to think beyond generating AI responses and focus on how AI reasoning could be combined with structured validation and deterministic logic.

It was also an opportunity to collaborate with teammates, exchange ideas, solve problems, and learn through implementation.

I'm grateful to my teammates and everyone involved in organizing the event for making this experience possible.

🎥 Project Demo

Watch the project demonstration:

DecisionShield — Demo Video

The demonstration introduces the main decision-review workflow:

Create a Decision
       |
       v
AI Analysis
       |
       v
Evidence Classification
       |
       v
Readiness Assessment
       |
       v
Missing Evidence
       |
       v
Stress Testing
       |
       v
Decision Stability
       |
       v
Decision Audit

For the full source code, visit the GitHub repository.

🙌 Final Thoughts

The most interesting part of building DecisionShield was not simply getting an AI model to generate an answer.

It was exploring a different question:

What if the most useful thing AI could tell us wasn't what to choose, but what we were missing before we chose?

That question is at the heart of DecisionShield.

Instead of asking only:

"What should I choose?"

We can also ask:

"Do I have enough evidence to make this decision?"

And if the answer is no, we should understand what information is missing, which assumptions need verification, and what risks deserve attention.

Building this project with Team Wakie Wakie at Hacktoberfest Hack Day Coimbatore was a meaningful step in learning, collaborating, and experimenting with open-source AI.

We look forward to learning more, improving the project, and exploring how AI can support more transparent and evidence-based decisions.

Built with ❤️ using open-source AI and Gemma 4.

What do you think AI's role in decision-making should be: recommending an answer, or helping us understand whether we're ready to make the decision?

I'd love to hear your thoughts in the comments!