Verikan User Guide

Everything you need to ask questions, read verified answers, and administer the concierge.

What is Verikan?

Verikan — your AI Data Concierge — is a chat assistant that lets you explore government and public open-data sources using plain English, with every answer backed by citations and independent verification. Instead of downloading CSV files and writing code yourself, you just ask a question and the system:

Signing In

A login is required to run new queries. Verified community notebooks can be browsed and downloaded without any account. Verikan uses GitHub sign-in.

1. 1
   Click the Login button in the top-right corner of any page, then Sign in with GitHub.
2. 2
   If your email is not yet on the approved list you will land on an "Awaiting Verification" page. An admin is notified automatically — access is typically granted within one business day.
3. 3
   Once approved, sign in again and you'll proceed straight to the chat. Your username appears in the navbar.

Guest Access

Without logging in you can still:

• Browse the landing page and example questions.
• View and download any Verified notebook from the community library.
• See answers that match a verified notebook (the system will serve the cached answer automatically).

To submit your own queries and generate new analysis you must be logged in.

Asking Questions

Type your question in natural language into the search bar on the landing page or the message box at the bottom of any open chat. Press Enter or click the button to submit.

The system works best when questions are:

• Specific about geography — mention the city, neighborhood, or county you care about.
• Focused on a single metric — "How many potholes were reported in Squirrel Hill last year?" works better than "Tell me everything about Pittsburgh infrastructure."
• Time-aware — include a year or date range where relevant ("in 2024", "last 6 months").

Example Questions

Here are the kinds of questions Verikan handles well:

311 Service Requests

• What are the most common types of 311 requests in Pittsburgh?
• Which neighborhoods generate the most 311 complaints?
• How long does it take the city to resolve pothole reports?
• Show me 311 request trends over the past three years.

Public Safety

• Which Pittsburgh neighborhoods have the most police incidents?
• What types of crime are most common in the Hill District?
• Show me year-over-year changes in reported incidents by type.

Building & Property

• How many building permits were issued in Pittsburgh last year?
• What is the distribution of property values across Pittsburgh neighborhoods?
• Which ZIP codes have the highest number of vacant properties?

Community & Demographics

• Show me community center attendance trends in Pittsburgh.
• What is the population breakdown by age group in Allegheny County?
• What is the median household income by neighborhood?

Data Sources

Verikan currently queries the following data sources:

Admins can register additional CKAN portals from the Admin Panel — see the CKAN Sites section below.

Verified Answers

When an admin approves a notebook submission it enters the Verified Library. Future questions that closely match a verified entry (≥ 50% semantic similarity) receive the pre-reviewed answer instantly — no new computation needed.

If a verified notebook scores between 40–49% similarity, the system shows a Similar Verified Notebook banner beneath the generated answer so you can quickly download the related community notebook.

Managing Conversations

• New Chat — click the blue New Chat button in the sidebar to start a fresh conversation.
• Switching chats — click any conversation in the left sidebar to jump back to it; all messages are restored.
• Searching — the sidebar search box filters conversations by title and message text.
• Renaming — click the pencil icon in the chat header (or double-click the title).
• Deleting a chat — click the icon on any sidebar item; you'll be asked to confirm.
• Persistent URLs — each conversation gets a unique URL (e.g. /#a3f9b2c1). Bookmark it or share the link to return directly to that chat.
• Cross-device sync — when logged in your chats are saved to the server and load automatically on any browser.

What is a Notebook?

Every answer generated by the AI is accompanied by a Jupyter Notebook (.ipynb) — a self-contained document that records exactly how the data was fetched, cleaned, and analyzed. Notebooks consist of two cell types:

Notebooks make analysis fully reproducible: anyone can download the file, run it in Jupyter or Google Colab, and arrive at the same numbers.

Viewing & Downloading

1. 1
   After the assistant responds, click the View Notebook button that appears under the message.
2. 2
   A full-screen viewer opens showing every code and markdown cell. Click any cell header to collapse/expand it. Use Collapse All / Expand All to manage long notebooks.
3. 3
   Click Download .ipynb to save the notebook to your computer.

Submitting for Review

If you receive a high-quality generated answer you think others would benefit from, you can submit the notebook for admin review. Once approved it enters the Verified Library and future similar questions receive an instant, trusted answer.

1. 1
   Open the notebook viewer (click View Notebook on any generated response).
2. 2
   Click Submit for Review in the modal footer.
3. 3
   An admin will review the submission, optionally add notes, and approve or reject it.

Running in Jupyter / Google Colab

Jupyter Lab / Notebook

1. 1
   Download the .ipynb file from the viewer.
2. 2
   Open a terminal and run pip install requests pandas if not already installed.
3. 3
   Launch Jupyter: jupyter lab and open the downloaded file.
4. 4
   Run all cells with Shift+Enter or Run → Run All Cells.

Google Colab

1. 1
   Go to colab.research.google.com.
2. 2
   Click File → Upload notebook and choose the downloaded .ipynb.
3. 3
   Click Runtime → Run all.

Admin Panel — Overview

The admin panel is organized into grouped sections in the left navigation:

Reviewing Submissions

When a user submits a notebook for review it appears in the Pending Review section with a badge showing the count. The Dashboard stats update too.

1. 1
   Click Review on any pending submission card to open the review modal.
2. 2
   The modal shows the original query, the full answer preview (Markdown rendered), a complete notebook preview with syntax-highlighted code, and the agent logs.
3. 3
   Enter a Reason — it is recorded with the decision (and in the GitHub commit).
4. 4
   Click Approve to add it to the Verified Library, or Reject to discard it. Both actions are permanent.

Approved Members

Only emails on the Approved Members list can gain access via social login. Users who sign in but aren't approved land on an "Awaiting Verification" page and a pending access request is generated automatically.

• Add an email — enter the email address in the form and click Approve. The user can sign in immediately.
• Pending requests — shown at the top of the section (and as a badge in the nav) when users are waiting; click Approve or Dismiss directly from there.
• Remove access — click next to any approved email to revoke login access.

CKAN Sites

Any CKAN-compatible open-data portal can be added as a data source. The agent will include it when searching for datasets — no restart required.

1. 1
   Click Add Site.
2. 2
   Enter the Portal Name (display label) and the CKAN Portal URL — the base URL without /api/3 (e.g. https://data.example.gov).
3. 3
   Optionally set a Site ID (auto-generated if blank), Default Organization slug, Description, Keywords, and a Quality Score (0–1, higher = preferred).
4. 4
   Click Add Site. The portal is available immediately for new queries.

MCP Servers

Model Context Protocol (MCP) servers extend Verikan with additional data capabilities beyond CKAN — such as the U.S. Census Bureau and FBI Crime Data Explorer servers that provide demographic and crime lookup tools.

Three transport types are supported:

• stdio (Process) — launches a local process (e.g. a Docker container or Node.js script). Requires a Command, optional Arguments, Environment Variables, and a Working Directory.
• SSE — connects to a remote server via HTTP Server-Sent Events. Requires just a Server URL.
• Streamable HTTP — connects to a remote server via the newer streamable-HTTP MCP transport. Requires just a Server URL.

Once added, click Connect on a server card to discover its available tools. Connected tools appear as chips and can be invoked directly from the admin panel for testing.

Query Logs

The Query Logs section records every question asked by logged-in users, whether it was served from the verified cache or freshly generated.

• User filter — narrow to a specific user's history.
• Source filter — filter by Generated, Verified cache, or Errors.
• Refresh — click the refresh button to pull the latest entries.

Each row shows the timestamp, user, query text, source, confidence score, and response time in milliseconds.

GitHub Notebook Publishing

Verikan can automatically push approved notebooks to a GitHub repository, keeping a public or private archive of all verified community analysis. Publishing is active whenever a repository and token are configured; use Pause to halt all GitHub I/O without erasing the token.

1. 1
   Go to Configuration → GitHub Publishing.
2. 2
   Paste a GitHub Personal Access Token (PAT) with repo write scope. Leave blank to keep the existing token.
3. 3
   Enter the Repository in owner/repo format, the Branch, and separate folder paths for draft and verified notebooks.
4. 4
   Click Save Settings, then Test Connection to verify everything is working.

Reviewing & Editing Notebooks on GitHub

The configured GitHub repository is the source of truth for the verified library. Every approved notebook is committed there, and any edits you make on GitHub flow back into Verikan automatically the next time the notebook is fetched (or immediately when an admin clicks Sync from GitHub in the Verified Library). This lets subject-matter experts review and correct analysis directly in GitHub — with full version history — without touching the app.

Where the notebooks live

Open the repository set in Configuration → GitHub Publishing (in owner/repo form). Notebooks are organized into folders configured there:

• Verified folder (default verified) — approved, published notebooks that power instant Verified Answers.
• Drafts folder (default drafts) — submissions awaiting review.
• Verified answers folder (default verified-answers) — approved quick answers.

Viewing & reviewing a notebook

GitHub renders .ipynb files natively — no download needed to read one.

1. 1
   Browse to the verified folder and click any .ipynb file. GitHub shows every markdown and code cell, plus any saved outputs, in order.
2. 2
   Read the cell-by-cell logic: which dataset was queried, the SQL/Python used, and how the final numbers were computed. Confirm the answer text matches the outputs.
3. 3
   Open the commit history (the clock icon, or the History button) to see who approved or edited it and why — the reviewer's reason is recorded in the commit message. Use Blame to see when a specific line changed.
4. 4
   From the app side, the same notebook — with its full agent logs and a Typed Standards verify link — is available in the admin Verified Library via View.

Validating reproducibility

To independently confirm a notebook produces the numbers it claims:

1. 1
   On the notebook's GitHub page, click Download raw file (or the raw button) to get the .ipynb.
2. 2
   Open it in Google Colab (File → Upload notebook) or local Jupyter, then Runtime → Run all / Run → Run All Cells.
3. 3
   Confirm the freshly-computed outputs match the committed ones and that every figure traces back to a cited source. Because notebooks fetch data live from the portal, small differences can indicate the underlying dataset was updated since approval.

Modifying a notebook

1. 1
   Small fixes — click the pencil on the file in GitHub to edit it in the browser, then commit with a clear message explaining the change.
2. 2
   Larger changes — clone the repo, edit and re-run the notebook locally in Jupyter, and open a pull request so the change can be reviewed before it merges to the publishing branch.
3. 3
   Once your edit is on the configured branch, it becomes the source of truth. Verikan picks it up automatically the next time that notebook is served, or right away when an admin clicks Sync from GitHub in the Verified Library.

Tips & Tricks

• Rephrase if the answer is wrong — try adding more context ("in the Hill District", "from 2022 to 2024") or simplifying the question.
• Use example questions as templates — click any of the pre-loaded examples on the landing page to see the format that works best.
• Bookmark your chat URL — each conversation has a unique hash URL; bookmark it to return directly.
• Download the notebook — even if you don't run it, the notebook shows the exact CKAN API calls used, which you can replicate manually.
• Check the confidence score — shown below freshly generated answers. Lower scores mean the model was less certain; treat those answers with extra skepticism.
• Press ? — opens the keyboard-shortcuts overlay in the chat.

FAQ

Why does the assistant say it can't find data?

The agent searches registered CKAN portals and connected MCP servers. If no relevant dataset is found it will say so honestly. Try rephrasing your question or ask an admin to register an additional data portal.

How recent is the data?

The assistant fetches data live from CKAN portals at query time, so results are as fresh as the portal's own update schedule. Most Pittsburgh/WPRDC datasets are updated daily to monthly.

Can I ask follow-up questions?

Yes — within the same conversation, continue typing follow-up questions. The assistant maintains context across messages in a single chat session.

Is my query logged?

When logged in, your queries are recorded in the server-side query log visible to admins. This helps improve the system and build the verified notebook library.

Why is a verified answer shown for a slightly different question?

The system uses semantic similarity to match questions — not exact text matching. If your question is at least 50% similar to a verified query, the cached answer is served. You can still ask for a fresh analysis by rephrasing to be more specific.

Who do I contact for access issues?

Contact your organization's Verikan administrator. If you used social login and are waiting for approval, your admin was notified automatically.