Socrates Platform

1. Platform Overview

Socrates is a two-sided marketplace platform where:

• Builders create, publish, version, and monetize AI tools of any type
• Users discover, run, save, fork, and pay for those tools — in-browser, instantly, with zero setup
• The platform handles hosting, execution, billing, safety, ranking, and analytics

Core Primitives

2. Architecture

Tech Stack

3. Data Models

Tool Schema

-- tools table (PostgreSQL)
CREATE TABLE tools (
  id            UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
  slug          TEXT        UNIQUE NOT NULL,   -- url-friendly id
  creator_id    UUID        REFERENCES users(id),
  name          TEXT        NOT NULL,
  description   TEXT        NOT NULL,
  type          tool_type   NOT NULL,           -- enum
  category      TEXT        NOT NULL,
  tags          TEXT[],
  icon_emoji    TEXT,
  
  -- The actual tool definition
  system_prompt TEXT,                                -- for prompt apps / agents
  input_schema  JSONB       NOT NULL DEFAULT '[]', -- field definitions
  output_schema JSONB,                               -- expected output structure
  sample_output TEXT,
  model_config  JSONB,                               -- model, temp, max_tokens, etc.
  tool_calls    JSONB,                               -- for agents: callable connectors
  
  -- Versioning
  version       TEXT        NOT NULL DEFAULT '1.0.0',
  changelog     TEXT,
  forked_from   UUID        REFERENCES tools(id),
  
  -- Monetization
  price_model   price_type  NOT NULL DEFAULT 'free',
  price_amount  NUMERIC(10,2),
  stripe_price_id TEXT,
  
  -- Status
  status        tool_status NOT NULL DEFAULT 'pending_review',
  is_featured   BOOLEAN     DEFAULT false,
  
  -- Timestamps
  created_at    TIMESTAMPTZ DEFAULT now(),
  updated_at    TIMESTAMPTZ DEFAULT now()
);

CREATE TYPE tool_type    AS ENUM ('prompt_app', 'chat_agent', 'workflow_agent', 'connector', 'model_wrapper', 'dataset');
CREATE TYPE price_type   AS ENUM ('free', 'monthly', 'per_run', 'one_time');
CREATE TYPE tool_status  AS ENUM ('pending_review', 'live', 'suspended', 'draft');

Input Schema (JSONB array)

[
  {
    "id":          "topic",
    "label":       "Essay Topic",
    "type":        "text",        // text | textarea | select | number | file
    "placeholder": "e.g. The fall of Rome",
    "required":    true,
    "options":     null           // only for "select" type
  },
  {
    "id":          "length",
    "label":       "Length",
    "type":        "select",
    "options":     ["Short", "Medium", "Long"],
    "required":    true
  }
]

User Schema (abbreviated)

CREATE TABLE users (
  id              UUID    PRIMARY KEY,
  username        TEXT    UNIQUE NOT NULL,
  email           TEXT    UNIQUE NOT NULL,
  role            TEXT    DEFAULT 'user',     -- user | builder | verified_builder | admin
  stripe_account  TEXT,                           -- Stripe Connect account ID
  balance_cents   INT     DEFAULT 0,
  created_at      TIMESTAMPTZ DEFAULT now()
);

CREATE TABLE runs (
  id          UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
  tool_id     UUID        REFERENCES tools(id),
  user_id     UUID        REFERENCES users(id),
  inputs      JSONB       NOT NULL,
  output      TEXT,
  model_used  TEXT,
  tokens_in   INT,
  tokens_out  INT,
  latency_ms  INT,
  rating      SMALLINT,  -- 1-5 star, user-provided
  thumbs      SMALLINT,  -- 1 = up, -1 = down
  re_ran      BOOLEAN    DEFAULT false,
  created_at  TIMESTAMPTZ DEFAULT now()
);

4. API Reference

All endpoints are RESTful JSON. Authentication via Bearer JWT. Rate limits apply per user tier.

Tools Endpoints

Run Endpoint

This is the most critical endpoint. It accepts user inputs, routes to the correct model, executes the tool, streams the output, and records analytics.

// POST /api/tools/:slug/run
// Request
{
  "inputs": {
    "topic":  "The fall of the Roman Empire",
    "length": "Medium",
    "tone":   "Academic"
  },
  "stream": true
}

// Response (streaming SSE when stream: true)
event: chunk
data: {"delta": "The Roman Empire, at its height..."}

event: chunk
data: {"delta": "...commanded over 70 million subjects..."}

event: done
data: {
  "run_id":    "run_abc123",
  "tokens_in":  312,
  "tokens_out": 874,
  "latency_ms": 1840
}

SDK & CLI

TypeScript/JavaScript SDK and a CLI for publishing tools and pulling run history are planned to wrap these REST endpoints with auth refresh and typed models. Track progress in the roadmap (Phase 4).

5. Pages & Flows

Marketplace Page /explore

• Left sidebar: Categories (16+), Type filters, Price filter
• Top bar: Full-text search (Typesense), Sort (Trending / Rating / Newest / Most Runs)
• Tool cards: Icon, name, type badge, description (3 lines), author, rating, run count, price
• Hover: Quick-run button, Fork button, Save to collection
• Trending section: Top 6 by trending score (recalculated every 15 min)
• Pagination: Infinite scroll with virtualization (react-window)

Publish Flow /studio/new

1. Step 1 — Type Selection: Pick primitive (Prompt App / Agent / Chat / Model / Connector / Dataset)
2. Step 2 — Details: Name (60 chars), description (200 chars), category, tags, icon emoji
3. Step 3 — Inputs & Prompt: Visual input field builder + system prompt editor with variable interpolation ({{variable}})
4. Step 4 — Test & Price: Live test against the real model + pricing model (free / monthly / per-run)
5. Step 5 — Review & Publish: Terms acceptance → submit for review (auto + human queue)

Run Flow /tools/:slug/run

• Tool landing page: description, examples, creator profile, rating histogram, recent outputs (anonymized)
• Run panel: dynamic form generated from input_schema, sample-fill button, "Test with example" button
• Execution: streaming output with typing animation, token counter, latency indicator
• Post-run: thumbs up/down, star rating, copy, share link, fork, "Run again with changes"
• History: Logged-in users see all previous runs for this tool with inputs/outputs

6. Monetization

Revenue Models

Socrates Credits

Users maintain a credit balance (like Roblox Robux). Credits are spent on per-run tools and can be purchased in bundles. This decouples payment from individual micro-transactions and reduces friction.

• 100 credits = $1.00
• Bulk discounts: 5K credits for $45, 20K for $160
• Builders set run cost in credits (minimum 1, typical 5–100)
• Platform takes 20% of credits redeemed by each builder

Builder Payouts

• Automatic monthly payout via Stripe Connect to builder's bank account
• Minimum payout threshold: $25
• Detailed earnings breakdown: by tool, by date, by revenue source
• Real-time balance visible in dashboard

7. Safety & Trust

Automated Checks (at publish time)

• Jailbreak detection: Scan system prompt for known bypass patterns using a fine-tuned classifier
• PII leak detection: Check if prompt could cause the model to output sensitive user data
• Malware patterns: Flag prompts designed to extract credentials, social-engineer, etc.
• CSAM / NSFW: Hard block on any content involving minors or explicit content (unless platform section is explicitly adult-gated)
• Output sampling: Run 10 internal test queries on every new tool before approval

Human Review Queue

• All new tools require human review before going live (<24h SLA)
• AI-flagged tools go to a priority review queue
• Verified Builders (track record, ID verified) get expedited review (<4h)

Runtime Safety

• Output moderation: Every run passes through a lightweight classifier before being returned to the user
• Rate limiting: Per-user and per-tool to prevent abuse
• User reporting: "Report" button on every tool and every run output
• Tool suspension: Automated tripwire if report rate spikes above threshold

8. Analytics System

The analytics system is a core competitive moat. It produces signals that power ranking, helps builders improve their tools, and creates data network effects as usage grows.

Events Captured (per run)

{
  "event":       "tool_run",
  "tool_id":     "uuid",
  "user_id":     "uuid | null",
  "session_id":  "uuid",
  "latency_ms":  1840,
  "tokens_in":   312,
  "tokens_out":  874,
  "thumbs":      1,        // 1=up, -1=down, 0=none
  "re_ran":      false,    // did user run this tool again within session?
  "copied":      true,     // did user copy the output?
  "forked":      false,
  "source":      "trending",// how they found it
  "category":    "writing",
  "timestamp":   "ISO8601"
}

Builder Dashboard Metrics

• Total runs / unique users / new users (by day, week, month)
• Retention: % of users who ran again (by 1d, 7d, 30d cohort)
• Success signals: thumbs up rate, copy rate, re-run rate
• Revenue: earnings by tool, by day, by source (subscription / per-run / fork)
• Search signals: what users searched to find the tool
• AI Insights: platform-generated recommendations ("add a follow-up option to boost retention")

9. Ranking Algorithm

Trending score is recalculated every 15 minutes. It rewards tools that users actually find valuable — not just ones with the most raw clicks.

10. Roadmap