Cosolvent

Build Without Boundaries

As part of the MarketForge ensemble, Cosolvent serves as the open-source layer. It provides the essential digital infrastructure that connects isolated buyers and sellers within highly specialized, low-volume ecosystems.

Rather than spending months building role permissions, deal-flow assembly, and semantic scaffolding from scratch, Cosolvent allows you to generate a functional marketplace structure instantly, ready to be customized for your exact vertical.

Core Features

• ✅ Matching Engine: Pre-built logic for resolving complex semantic matches.
• 🔜 Deal Assembly: Manage the multi-step lifecycle of thin market deals through the story-progression deal engine — in active development (see feature sheet).
• ✅ Role Permissions: Native support for multi-party structures, including facilitators and intermediaries.
• ✅ Open Source: MIT License ensures you own and control what you build.

The Content Match Story — Knowing Before Committing

Most matching platforms announce a match. Cosolvent argues for one.

When two parties are matched, Cosolvent generates a Content Match Story — an AI-authored narrative that explains why the pairing is promising and what they could plausibly accomplish together. Not a profile summary. Not a referral. A case, made on behalf of the match.

Delivery is progressive and privacy-respecting: the story begins anonymously, so both parties can assess fit before any identifying information is exchanged. Identity is revealed only on double opt-in. This means participants arrive at their first conversation already understanding the match argument — wasted calls drop, conversion on genuine matches rises, and every interaction starts with shared context rather than mutual assessment from scratch.

In thin markets — where each viable match is rare and every trust withdrawal is costly — the Content Match Story is not a convenience feature. It is a structural intervention that makes low-density markets viable.

The Deal Brief — Platform’s Primary Deliverable

These are not two separate features. The Deal Brief is the finished form of the Content Match Story — the same document at a later level of refinement and completeness, matured as successive versions are read, corrected, and confirmed by the parties.

Every Cosolvent marketplace ends at the same point: a Deal Brief. It is not generated at the end — it is the last confirmed version (the final milestone) of the match story, enriched along the way by profiles, matching signals, dialogue, facilitator input, and regulatory context. It captures:

• 📋 Agreed terms — what both parties have consented to
• ❓ Open items — what remains to be resolved, with each party’s last position
• 👥 Role slots — which facilitators (attorneys, inspectors, freight forwarders, insurers) need to act
• 📜 Regulatory checklist — compliance steps required before the transaction can execute
• ➡️ Next steps — who needs to do what, in what order

The Deal Brief is explicitly not a contract. It is the document the parties hand to their own attorneys to draft the contract. This design is deliberate: in thin markets, participants are cautious about platform lock-in, and the transactions are too complex for automated contracting. The platform’s job is to get the parties to a meeting of the minds. The downstream professionals handle the commitment.

Scope Boundaries: What We Build vs. What You Build

Cosolvent is deliberately architected as a headless marketplace engine. It provides the universal infrastructure for thin market formation, but explicitly defers the participant-facing interface to the market sponsor.

• ❌ Frontend UIs: Cosolvent provides APIs. The vertical sponsor builds the web or mobile app.
• ❌ Monetization & Payments: We defer payment processing and business models to existing tools like Stripe.
• ❌ Trust & Verification: Escrow, dispute resolution, and regulatory compliance are handled by the sponsor.
• ❌ Digital Twins: Simulated populations belong in ClientSynth, separated from live market data.

Configuration & Deployment

✅	YAML-Driven Marketplace Definition	Define participant types, schemas, permissions, and discovery settings in a single marketplace.yaml file.
✅	Deterministic Compiler Pipeline	YAML → normalize → hash → render → write → manifest. Reproducible artifact generation with drift detection.
✅	Browser-Based Setup Panel	Visual configuration UI with presets, real-time validation, and live YAML preview.
✅	Docker Compose Deployment	Single-command launch: API server, PostgreSQL + pgvector, Redis, ARQ background workers.
🔜	AI-Assisted Configuration	AI assistant generates config suggestions from conversational market description.
🔜	Multi-Tenancy	Tenant isolation for hosting multiple marketplaces on a single deployment.

Profile Infrastructure

✅	Dynamic Profile Schemas	Runtime Pydantic models generated from config. No hard-coded entity types.
✅	Three-Tier Field Visibility	Every field tagged public, protected, or private with enforcement at the API layer.
✅	Configurable Onboarding	Per-type onboarding: manual/auto approval, document uploads, AI extraction, completeness thresholds.
🔜	Gallery / Matching Separation	Split into a curated gallery layer (browsing) and a richer matching layer (AI-only signals).
🔜	Group / Cooperative Type	Groups of small producers participate as a single entity with aggregated profiles.

AI & Semantic Search

✅	AI Document Extraction	LLM reads uploaded documents and extracts structured profile fields automatically.
✅	Semantic Vector Search	pgvector cosine-distance search with metadata filtering and configurable thresholds.
✅	Hybrid & RAG Search	Two retrieval modes — hybrid (vector + keyword) and rag_strict (vector-only with grounding).
✅	Multi-Provider AI	Provider-agnostic LLM layer supporting OpenAI, OpenRouter, and Google Gemini.
🔜	CommonContext Integration	Sponsor-curated domain knowledge library with vertical-specific metadata and domain Q&A.
🔜	VLM Integration	Image-based document extraction for certificates, invoices, and product photos.

Matching & Deal Engine

✅	Participant Discovery	Config-driven search with filter fields, anonymous/authenticated results, and similarity thresholds.
🔜	Bidirectional Matching	Mutual preference matching considering both parties' profiles.
🔜	Deal Data Model	Structured deals linking principals, facilitators, and role slots — maintained as a chain of immutable match-story versions with per-party acknowledgment, so every milestone is an account all parties have read and confirmed.
🔜	Deal Brief	Platform's primary deliverable — the rendering of the final, complete milestone of the match story: a structured, non-binding summary of agreed terms, open items, role slots, and next steps, designed as input for the parties' own attorneys and advisors.
🔜	Anticipatory Matching	Proactive notifications when new listings match a participant's needs.

AI Risk Insulation & Contingency Structures

The AI Risk Insulation module addresses externally imposed market uncertainty (EMU). Monitoring real-time macro-economic feeds—central bank daily exchange rates, tariff registries, corridor shipping logs, commodity price indexes—it drafts recommended contingency structures for the deal: currency collars, tariff cost-splits, and regulatory escape triggers, carried as a structured section of the Deal Brief.

This counters the Option Value of Delay in volatile macro environments: instead of freezing while conditions shift, the parties arrive at their attorneys with pre-negotiated contingency terms ready to be adapted into the real agreement. Consistent with the platform's scope, Cosolvent drafts and monitors; executing any contract, escrow, or settlement mechanism belongs to the parties and their own professionals and providers.

Structured Contingency Schema (a Deal Brief section)

Below is an example of the structured contingency section a Deal Brief can carry — a currency collar, tariff threshold split, and regulatory compliance escape trigger — ready for the parties' attorneys and settlement providers to adapt into the authoritative agreement.

{
  "contingency_id": "dcc_8f3a9d2c_412e",
  "principals": {
    "buyer": "buyer_firm_109",
    "seller": "seller_firm_304"
  },
  "financials": {
    "base_amount": 125000.00,
    "currency": "USD",
    "settlement_type": "prog_escrow"
  },
  "ai_risk_insulation": {
    "currency_collar": {
      "reference_pair": "CAD_USD",
      "oracle_source": "central_bank_feed",
      "base_rate": 0.7350,
      "lower_floor": 0.7100,
      "upper_ceiling": 0.7600,
      "contingency": {
        "action": "adjust_pro_rata",
        "formula": "price * (current_rate / base_rate)"
      }
    },
    "tariff_indexation": {
      "commodity_code": "1001.99.00",
      "transit_corridor": "CA_US_border_windsor",
      "base_tariff_pct": 0.05,
      "max_tariff_cap": 0.15,
      "escalation_contingency": {
        "split_ratio": { "buyer": 0.5, "seller": 0.5 },
        "action": "terminate_with_full_refund_above_cap"
      }
    },
    "regulatory_escape": {
      "required_registries": [
        "fda_import_compliance",
        "cfia_export_certification"
      ],
      "check_frequency_seconds": 3600,
      "contingency": {
        "trigger_on_revocation": true,
        "action": "automatic_force_majeure_refund",
        "escrow_resolution": "return_to_buyer"
      }
    }
  }
}

🔜	Macro Feed Ingestion Pipeline	Integrations for official central bank daily FX rates and tariff lookup APIs, feeding the contingency drafting.
🔜	Currency Collar Structuring	Drafts recommended adjustment ranges to cushion buyer/seller margins from unexpected intraday or multi-day FX drops.
🔜	Escrow-Ready Structures	Contingency terms formatted so the parties' own escrow or settlement providers can implement them directly.
🔜	Tariff Cost-Splitting Recommendations	Recommends fair apportionment of border cost increases between transacting parties based on real-time customs database queries.
🔜	Force Majeure Flagging	Flags force-majeure conditions in active deals — e.g., a crucial regulatory certificate revoked mid-transit — and recommends the corresponding escape terms for the parties to act on.

Communication

✅	Conversation Lifecycle	Create, accept, reject, and close conversations with full state tracking.
✅	Real-Time WebSocket	Live message delivery via WebSocket connections.
✅	Config-Driven Rules	Conversation initiation rules defined per participant-type pair in marketplace config.
🔜	Progressive Trust Gating	Communication channels unlock progressively as trust stages advance.

Trust & Verification

✅	Admin Approval Workflow	Binary trust gate — admin manually approves or rejects participant applications.
🔜	Verification Pipeline	Auto-analyze documents for consistency and assign verification confidence scores.
🔜	Reputation System	Track transaction outcomes, response times, and dispute rates.
🔜	Progressive Trust Stages	Six-stage trust ladder from anonymous browsing to post-transaction evaluation.

Admin & Developer Tools

✅	Admin Dashboard	Aggregate marketplace statistics, user management, and application approval.
✅	OpenAPI Documentation	Auto-generated interactive API docs at /docs.
✅	Drift Detection	compile --check verifies generated artifacts match current config.
✅	36+ Unit Tests	Coverage across config, compiler, permissions, visibility, schemas, and more.
✅	Background Job Processing	ARQ worker pool for async document processing, embedding generation.

Architecture

Language	Python 3.11+
API Framework	FastAPI
Database	PostgreSQL + pgvector
Cache / Queue	Redis + ARQ
AI Providers	OpenAI · OpenRouter · Google Gemini
License	Open Source (MIT)