• 

💡 What Inspired Us Every powerful AI demo I had ever seen shared the same silent flaw: the AI just agreed. You'd describe a half-baked idea, and the model would enthusiastically elaborate on it, hallucinate supporting evidence, and hand you something that felt like progress but wasn't.

The real bottleneck in knowledge work isn't access to information — it's quality of thinking. The best collaborators in the room aren't the ones who nod along; they're the ones who say "wait, have you considered the failure mode here?"

I wanted to build an AI that behaves more like a senior colleague than a yes-machine — one that can challenge your assumptions when that's what you need, synthesize research when that's what you need, co-design a solution when ambiguity is high, or simply execute without ceremony when the problem is already well-defined.

That question — "What does collaboration actually look like, at each stage of a problem?" — became the seed of CollabPartner.

🔨 How I Built It The architecture is a FastAPI autonomous agent engine powered by Gemini 2.5 Flash, with four layers working in concert:

1. The Four Collaboration Modes The agent is not a single persona. It routes itself into one of four distinct behavioral modes based on the nature of the user's request:

Mode Trigger Signal Behavior 🥊 Sparring Partner High expertise + opinionated input Devil's advocate, stress-tests assumptions 🔍 Research Assistant Open-ended exploratory question Neutral aggregation, multi-perspective summaries 🏗️ Co-Architect High ambiguity + high complexity Formal 4-phase protocol with gate exit criteria ⚡ Executor Well-defined, direct task Zero friction, maximum delivery speed The Co-Architect mode enforces a structured state machine:

INTAKE → FRAMING → APPROACH → EXECUTION → VALIDATION INTAKE→FRAMING→APPROACH→EXECUTION→VALIDATION Each phase has non-negotiable exit criteria — the agent cannot advance without satisfying them. This prevents the common failure mode where an AI rushes to a solution before the problem is even properly understood.

1. Structured Collaboration Skills (Slash Commands) Three formal skill protocols wire the structured intelligence together:

/user-working-style-profiler — Elicits the user's Cognitive Style (Top-down vs. Bottom-up), Expertise Depth on a scale d ∈ [ 1 , 5 ] d∈[1,5], Decision Authority, and Constraint Stack. Every subsequent response is calibrated to this profile.

/problem-statement-contract — Before any collaborative work begins, the agent builds and requires the user to sign a Problem Statement Contract (v1.2) capturing: Core Question, Success Criteria, Known Constraints, Unknowns/Assumptions, Stakeholders, and a Revised Problem Statement (the real problem, not just the symptom).

/collaboration-phase-exit-criteria — Enforces phase gates as a reproducible state machine so the agent behaves consistently, not differently every session like a chatbot.

1. Document-Grounded RAG with Zero-Hallucination Mode For document Q&A (legal briefs, technical specs, design documents), the agent uses a real-time text chunking and similarity retrieval pipeline. Answers are grounded exclusively in uploaded document text, with every claim cited by chunk ID ([Source: chunk_3]). If the answer is not in the document, the agent says so.

The retrieval ranking uses cosine similarity over TF-IDF-weighted vectors:

sim ( q , d i

)

q ⃗ ⋅ d i ⃗ ∣ q ⃗ ∣

∣ d i ⃗ ∣ sim(q,d i ​ )= ∣ q ​ ∣ ∣ d i ​

​ ∣ q ​ ⋅ d i ​

​

​

where q ⃗ q ​ is the query embedding and d i ⃗ d i ​

​ is the i i-th document chunk embedding.

1. Async Background Task Queue Long-running workflows (multi-step research synthesis, large document indexing) are offloaded to an asynchronous task queue so interactive multi-turn dialogue is never blocked. Users get a task ID and can poll for results without freezing the conversation.

2. Firebase Firestore Persistence User profiles, signed Problem Statement Contracts, session states, and phase completion history are persisted in Firebase Firestore — with an in-memory mock store for local development so there are no hard dependencies on cloud infra to get started.

3. Security-First from Day One The entire stack is hardened against OWASP Top 10 Web and OWASP Top 10 for LLM Applications:

Prompt injection → automated pattern matching + system prompt boundary isolation before every LLM call. Sensitive data disclosure → regex output scrubbing strips API keys, JWTs, and secrets from model responses before they reach the client. Cross-user data leaks → strict Firestore document key separation per user_id, enforced at every read/write. XSS / code injection → HTML and script tag stripping on all prompt inputs. Secret exposure → .gitignore and .dockerignore hard-block .env, service_account.json, and key files. The app is containerized with Docker and deploys to Google Cloud Run with a single gcloud run deploy command.

📚 What I Learned

1. Structure is not the enemy of creativity — it's what makes creativity safe. The 4-phase collaboration protocol feels rigid on paper. In practice it produces far richer outputs because neither the user nor the AI is allowed to skip the uncomfortable "what are we actually solving?" conversation.

2. LLM security is an active discipline, not a checkbox. Prompt injection isn't theoretical. Building the sanitization layer exposed just how many surface-area vectors a production LLM app has — from system prompt boundary violations to tool payload injection. OWASP's LLM Top 10 became a daily reference, not a post-launch audit.

3. Mode-switching > prompt engineering. Early prototypes tried to handle all collaboration styles with one elaborate system prompt. The moment I separated them into discrete behavioral modes with their own exit criteria, response quality jumped dramatically. Less ambiguity in the prompt = better, more consistent agent behavior.

4. Async is non-negotiable for agentic systems. The moment your agent does anything that takes more than 2 seconds, blocking HTTP is the wrong model. The background task queue was one of the most impactful architectural decisions — it transformed the UX from "waiting on AI" to "AI working while you think."

5. The hardest part of AI is knowing when NOT to answer. The zero-hallucination RAG mode required actively training myself (and the system prompt) to be comfortable with "I don't have enough information to answer this from the provided document." That epistemic humility is a feature, not a limitation.

🧱 Challenges Faced Challenge 1 — Enforcing Phase Gates Without Feeling Robotic The biggest UX tension was making the structured 4-phase protocol feel like a natural conversation, not a bureaucratic form. The solution was framing every gate check as a question, not a blocker — the agent asks rather than refuses.

Challenge 2 — Stateless LLMs in a Stateful Protocol Gemini, like all LLMs, is stateless per call. Maintaining the collaboration state (which phase are we in? what did the user sign in the contract?) required careful session management in Firestore, with the current state injected into the system prompt on every turn.

Challenge 3 — RAG Grounding Without a Vector Database Standing up a full vector DB (Pinecone, Weaviate) in a hackathon window wasn't realistic. I implemented a lightweight TF-IDF cosine similarity retriever entirely in Python — good enough for document-scale retrieval, deployable with zero external dependencies.

Challenge 4 — Security Without Killing Performance Every OWASP mitigation adds latency. Regex scrubbing, input sanitization, tool payload validation — each is cheap individually, but stacked they add up. The solution was pipelining: security checks run as a pre-hook before the LLM call (input) and a post-hook after (output), with the heavy async work offloaded to the background queue.

Challenge 5 — Keeping the Agent "Honest" About Its Mode Early versions of the agent would silently drift out of Sparring Partner mode into agreeable Executor behavior after a few turns. The fix was embedding the active mode as an explicit [MODE: SPARRING_PARTNER] token in the persistent system context, forcing the model to re-anchor its persona on every generation.

🎯 What's Next Voice interface — same 4-phase protocol, real-time audio streaming via Gemini Live. Multi-user collaboration rooms — shared Problem Statement Contracts, multiplayer phase progression. Evaluation harness — automated scoring of collaboration quality using a second Gemini instance as a judge.

Built With

• cloud-run
• fastapi
• firebase
• gemini-2.5-flash
• gemini-3.5-flash
• google-antigravity