BidLens

An evidence-grounded Gemini and Google ADK agent that finds matching U.S. federal opportunities and evaluates whether your company should bid.

Comment

Inspiration

Federal opportunities are difficult for small suppliers to evaluate. A single SAM.gov notice may contain structured metadata, multiple attachments, amendments, set-aside requirements, deadlines, and dozens of compliance conditions.

This creates two practical questions:

  1. Which live federal opportunities fit my company?
  2. Does a specific opportunity fit my company well enough to justify pursuing it?

We built BidLens to answer both questions without treating an AI-generated response as a verified fact or a final bidding decision.

What it does

BidLens provides two entry paths:

  • Discover opportunities: A supplier describes its services, NAICS code, service area, registrations, capabilities, and known limitations. BidLens searches SAM.gov live and produces an explainable metadata screen across multiple opportunities.
  • Analyze a known opportunity: A supplier enters a SAM.gov URL, Notice ID, or Solicitation Number. BidLens resolves that identifier exactly and asks the user to confirm the target.

After the user explicitly selects one opportunity, both paths enter the same eight-stage evidence pipeline:

  1. Retrieve the opportunity from the SAM.gov Opportunities Public API.
  2. Fetch public attachments into memory and parse text-based PDFs.
  3. Keep API facts and document evidence separate, preserving sources and conflicts.
  4. Compare the opportunity with the company profile using match, not_match, or unknown.
  5. Produce a conservative go_candidate, no_go_candidate, or review_required recommendation.
  6. Generate a traceable compliance matrix, open-item list, and editable response draft.
  7. Use Google ADK and Gemini 3.5 Flash to propose clarification questions and audit suggestions.
  8. Record human review decisions against content fingerprints so outdated decisions cannot silently carry forward.

Any explicit not_match — including an expired response deadline — produces a no_go_candidate. Missing or incomplete evidence, any unknown, or unresolved source conflicts produce review_required; they never become an automatic pass.

BidLens never prices, signs, certifies, or submits a bid. Every response package remains submission_ready=false and requires human confirmation.

How we built it

BidLens uses:

  • Python 3.13 and a lightweight standard-library HTTP backend
  • A vanilla JavaScript, HTML, and CSS interface with English and Chinese display modes
  • SAM.gov Opportunities Public API v2 for live opportunity data
  • Scrapling for official public requests
  • pypdf for in-memory PDF text extraction
  • Google ADK 2.8 with an InMemoryRunner
  • Google GenAI SDK (google-genai) to create the Vertex AI client passed into the ADK Gemini model adapter
  • Gemini 3.5 Flash through Vertex AI
  • Pydantic structured output for model responses
  • Application Default Credentials so Google credentials never enter the browser or repository
  • Docker and a verified private Cloud Run baseline revision. This revision validates the backend pipeline and Gemini/Vertex AI integration; it predates the current dual-entry interface, which is demonstrated locally and reproducible from the public repository.

The deterministic pipeline runs before Gemini. The model receives only a restricted, traceable evidence packet and may generate clarification questions or audit notes. It cannot modify deadlines, source facts, qualification results, recommendations, or submission status. If the model is unavailable or returns invalid output, the deterministic results remain intact.

Challenges we ran into

The most important challenge was deciding where AI should — and should not — have authority.

A fluent model response can appear more certain than the underlying evidence. We therefore separated deterministic gates from AI assistance and made unknown a first-class state.

Other challenges included:

  • Detecting scanned or unreadable PDFs without guessing their contents
  • Preserving potential amendment relationships without assuming that one filename replaces another
  • Keeping opportunity-level API facts separate from document-derived candidate requirements
  • Binding human audit decisions to the exact content rather than only a row ID
  • Moving from geographically unavailable Google AI Studio access to Vertex AI using Application Default Credentials
  • Safely handling partial attachment failures, timeouts, malformed model output, and repeated runs

Accomplishments that we're proud of

We completed a real eight-stage run against solicitation 1232SA26Q1088.

BidLens:

  • Retrieved the opportunity from a live SAM.gov search
  • Fetched all five public attachments; four were parsed as text PDFs, while one was correctly flagged as requiring OCR without inventing its contents
  • Ran 72 qualification checks: 49 match, 0 not_match, and 23 unknown
  • Detected a potential amendment relationship requiring human resolution
  • Produced a 64-row compliance matrix, 39 editable draft sections, and 26 open items
  • Kept the recommendation at review_required
  • Preserved submission_ready=false throughout the workflow

A real Gemini 3.5 Flash call through Google ADK, the Google GenAI SDK, and Vertex AI generated clarification questions and audit suggestions without changing the underlying recommendation or evidence.

The project currently collects 172 deterministic tests. Of these, 171 pass in the current environment; one host-binding assertion is blocked by the local sandbox's socket permission rather than by application logic.

The complete source code, architecture, setup instructions, and test suite are available in the public repository.

What we learned

In a compliance-sensitive workflow, the safest role for an LLM is not to make the final decision. It is to identify missing information, surface ambiguity, and help a human review traceable evidence.

We also learned that:

  • unknown is not a failure — it prevents unsupported conclusions.
  • Human review must be bound to content, not just record IDs.
  • Safe degradation is more valuable than fabricated fallback output.
  • Opportunity discovery and single-opportunity analysis should share one evidence engine rather than maintain two inconsistent decision systems.

Development disclosure

BidLens was built during the hackathon submission period. OpenAI Codex and Anthropic Claude Code were used as AI coding assistants. Third-party open-source libraries, Google SDKs, public APIs, and public data sources used by the project are identified above and in the public repository.

What's next for BidLens

Next steps include:

  • Independently verified company profiles and credentials
  • Human-confirmed OCR for scanned solicitation documents
  • Additional rule packs for bonding, ITAR, facility clearances, insurance, and other requirements
  • Multi-opportunity watchlists using the same evidence and audit model
  • A production-ready deployment with authentication, monitoring, persistent user-controlled profiles, and formal security review

Built With

Share this project:

Updates

Submission history