Mikono

This is a submission for Weekend Challenge: Generosity Edition

This is a submission for Weekend Challenge: Generosity Edition

The gap I kept seeing

During the pandemic I coordinated Red Cross distributions in Uasin Gishu County:
food, cash, PPE, hospital supplies, vaccines. The hardest days were never about
money. A shipment of supplies would sit at a depot because the one volunteer who
could drive it was signed up ten kilometres away, listed under a task nobody
connected to the need. A clinic needed someone to fix a cold-chain fridge; a
retired technician two streets over would have done it for free. Neither knew the
other existed.

The willing hands were always there. What was missing was a way to connect
"I can do X" to "we need X" when the two are never written in the same words.
That gap is what I spent this weekend building for.

What I Built

Mikono is a generosity exchange for skills and time, not money. People post
what they can do and small causes post what they need, both in plain language,
and Snowflake Cortex matches them by meaning.

A school needs someone to fix the computers. A women's savings group needs
someone who understands bookkeeping. A food bank has donations across town and no
way to move them. The willing helpers exist. Keyword search can't connect them,
because the two sides never use the same words.

A school writes "the computer lab machines will not switch on." A volunteer
writes "I fix broken laptops." Those two sentences share zero words. A
LIKE '%...%' search finds nothing. Mikono's semantic match scores them 0.73
and puts them together.

"Mikono" is Swahili for hands. The whole idea is offering a hand, not a wallet.

Three things it does:

• A live match board. Every cause paired with its best-fit volunteer, ranked, each with a plain-language reason for the match, all generated by Cortex in the warehouse.
• "I need help." A cause types its need in plain language and gets the top volunteers back instantly, matched on meaning.
• "I can help." A volunteer types what they can offer and sees the causes that fit, with an honest low score when nothing really matches.
• Bilingual by default. Type a need or offer in Swahili and Cortex TRANSLATE normalises it to English before matching, so "Ninaweza kutengeneza kompyuta" finds the same broken-computers cause as "I fix computers". Generosity here is bilingual; the matching has to be too.

Demo

🔗 Live public demo (open it, no login needed):
https://mikono-a6k75rt3xskpyybxwzvvea.streamlit.app/

The demo runs the exact same app on Streamlit Community Cloud, connected to
Snowflake as a locked-down read-only user (read + Cortex only, capped by a
resource monitor). The same code also runs inside Snowflake as a
Streamlit-in-Snowflake app on the active Snowpark session, with the "post to the
board" actions enabled.

The matches the semantic engine produced from the seed data, none of them share
keywords with the need:

Cause	What they wrote	Matched volunteer	Score
Uhuru Primary School	"computer lab machines will not switch on"	Amina - "I fix broken laptops"	0.73
Harvest Food Bank	"struggle to collect and deliver without transport"	Hassan - "I drive a pickup"	0.82
Coastal Health Outreach	"someone medical for simple screenings"	Esther - nurse	0.70
Furaha Women's Group	"savings records are a mess, need someone who understands money"	Brian - accountant	0.68
Bookmark Literacy Trust	"books in English, families read Swahili"	Grace - translator	0.64

Code

lewisawe / mikono

Mikono — a generosity exchange for skills and time

Most giving tools move money. Mikono moves hands. People post what they can do (fix laptops, tutor kids, drive a pickup, translate) and small causes post what they need, both in plain language. Snowflake Cortex matches them by meaning, so "I repair computers" finds "our lab machines won't switch on" even though the two sentences share no words.

Built for the DEV Weekend Challenge: Generosity Edition.

Why meaning, not keywords

Real needs and real offers almost never use the same words. A school writes "the computer lab machines will not switch on." A volunteer writes "I fix broken laptops." Keyword search scores that pair 0.0 (see app/verify_matching.py) Cortex embeddings score it 0.62 (and 0.73 once the blend adds category and location agreement). That gap is the whole reason this runs on Snowflake Cortex instead of LIKE '%...%'.

…

View on GitHub

The pieces:

• sql/01_schema.sql: two tables (OFFERS, NEEDS), each with a VECTOR(FLOAT, 768) embedding column.
• sql/03_embed.sql: enriches every row with EMBED_TEXT_768 and CLASSIFY_TEXT.
• sql/04_match.sql: the blended match view.
• sql/05_readonly_role.sql: a locked-down read-only role + user for the public demo, capped by a resource monitor.
• app/run_pipeline.py: runs the whole pipeline against a Snowflake account in one command. app/deploy_streamlit.py deploys the app the same way.
• app/verify_matching.py: a pure-Python mirror of the ranking, no Snowflake needed, so anyone can check the logic offline.

How I Built It

Snowflake Cortex is the engine, not a database bolted on. The intelligence
is the matching, and it runs entirely in SQL using five Cortex capabilities:

• EMBED_TEXT_768 turns each free-text offer and need into a 768-dim semantic vector.
• VECTOR_COSINE_SIMILARITY ranks offers against needs by meaning.
• CLASSIFY_TEXT labels each side into a help category (tech repair, healthcare, translation, and so on).
• TRANSLATE normalises a Swahili or Sheng query to English before matching, so the exchange works across the languages people actually write in.
• COMPLETE (llama3.1-8b) writes a one-line next step for each match: not "why they fit" in the abstract, but the concrete first action, e.g. "Amina diagnoses the computer lab machines to find the source of the problem."

The core of the match:

(0.70 * VECTOR_COSINE_SIMILARITY(need.embedding, offer.embedding)
 + 0.15 * IFF(need.category = offer.category, 1, 0)
 + 0.15 * IFF(need.location = offer.location, 1, 0)) AS blended_score

Why blend three signals. Pure semantic similarity is strong but occasionally
fooled by shared context words. In my first run, a school's "computer lab
machines won't switch on" matched a teacher instead of the laptop-repair
volunteer, because both mentioned "primary school." Adding a boost when Cortex's
CLASSIFY_TEXT puts both sides in the same category fixed it, and a small
same-location boost rewards matches that can actually happen (generosity is
local: a nurse across the country can't run a clinic day next week). Similarity
stays dominant at 70%, so no one is matched to the wrong skill; category and
location only break ties. Both extra signals still come from the data Cortex
produced. That's a design choice worth showing, not hiding.

Trust the SQL by reimplementing it. app/verify_matching.py mirrors the
ranking in plain Python with a bag-of-words stand-in for the embedding. It's
illuminating: on the hardest pairs ("machines won't switch on" vs "I fix
laptops") bag-of-words scores 0.0, while Cortex embeddings score 0.62.
The local mirror proves the ranking math is correct; the gap between the two
proves why the embedding has to be semantic.

Region-aware setup. smoke_test.py checks which Cortex models this account's
region actually exposes before the pipeline runs, so a missing model is caught
on one cheap call instead of mid-pipeline. (My region has EMBED_TEXT_768 and
llama3.1-8b, not mistral-large2, and the smoke test surfaced that up front.)

The app is Streamlit in Snowflake. It uses the active Snowpark session, so no
credentials live in the code, and the "I need help / I can help" tabs fire live
Cortex queries on whatever a visitor types.

Honest limits. The seed data is synthetic. A real deployment needs identity
and safeguarding for volunteers working with children before it touches the
public. The point of the weekend build is the matching engine, and that part is
real, running, and something I would have used on those distribution days: a way
for a willing hand and a real need to find each other without either having to
guess the other's words.

Prize Categories

Best Use of Snowflake. Cortex is the whole engine. Embeddings, cosine
ranking, text classification, translation, and the next-step lines all run as SQL
in the warehouse, and the app is a Streamlit-in-Snowflake app on the active
session. Nothing leaves Snowflake. The verify_matching.py mirror exists to show
that the semantic capability Cortex provides does work keyword matching cannot.