Skip to content

Commit 7c69ea5

Browse files
committed
Merge PR #7: productionize pairwise digital-twin evaluation
# Conflicts: # .github/workflows/ci.yml # README.md # backend/app/main.py # backend/app/standalone_server.py # backend/app/storage.py # backend/tests/test_ops_readiness_check.py # scripts/validate_update_manifest.py
2 parents ad6fc40 + f2910c3 commit 7c69ea5

70 files changed

Lines changed: 30347 additions & 101 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.env.example‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,3 +43,15 @@ CORTEX_EMBEDDING_MODEL=text-embedding-3-small
4343
CORTEX_EMBEDDING_DIMENSIONS=384
4444
CORTEX_EMBEDDING_STRICT=0
4545
OPENAI_API_KEY=
46+
47+
# Pairwise evaluation preflight admission. These are operator-owned ceilings;
48+
# request callers can tighten them but cannot raise them.
49+
CORTEX_PAIRWISE_MAX_PROVIDER_CALLS=1000
50+
CORTEX_PAIRWISE_MAX_TOTAL_TOKENS=10000000
51+
CORTEX_PAIRWISE_MAX_DURATION_SECONDS=86400
52+
CORTEX_PAIRWISE_MAX_PARALLEL_GENERATIONS=1
53+
CORTEX_PAIRWISE_MAX_PARALLEL_JUDGMENTS=1
54+
# Optional: enables short-lived, user-bound admission receipts. Use a distinct
55+
# random secret of at least 32 bytes; do not reuse an API or provider key.
56+
CORTEX_PAIRWISE_ADMISSION_SIGNING_KEY=
57+
CORTEX_PAIRWISE_ADMISSION_RECEIPT_TTL_SECONDS=900

‎.github/workflows/ci.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,8 @@ jobs:
1818
name: Python checks and backend tests
1919
runs-on: ubuntu-latest
2020
# The backend suite alone approaches ten minutes on some runners; this job
21-
# also runs SDK, examples, and evaluation gates. Preserve failure headroom.
21+
# also runs SDK, examples, pairwise evaluation, and other quality gates.
22+
# Preserve headroom for dependency installation and runner variance.
2223
timeout-minutes: 30
2324

2425
steps:

‎README.md‎

Lines changed: 42 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,47 @@ returns source citations—or explicitly abstains when the evidence is not there
3434
> follow the beta**. If something breaks, tell us—the project is built in the
3535
> open and the rough edges are documented.
3636
37-
## Why Cortex exists
37+
## What Cortex does today
38+
39+
Cortex is a **macOS beta**. It runs a local engine on your Mac that ingests your notes and AI-chat
40+
exports, turns them into typed and cited memory you review, and serves that memory to AI tools over
41+
MCP.
42+
43+
Concretely, today you can:
44+
45+
- **Bring in your history.** Drop in a ChatGPT, Claude, Gemini, Notion, Slack, Discord, or Telegram
46+
export — or mbox/eml, `.ics`, `.vcf`, DOCX, Zoom transcripts, browser bookmarks, an X or LinkedIn
47+
archive, and more. See [`docs/SOURCE_IMPORTS.md`](docs/SOURCE_IMPORTS.md).
48+
- **Sync live sources with a key you paste.** GitHub (secretless device-flow sign-in), Slack, Linear,
49+
Jira, Readwise, Raindrop, Zotero, Calendar, Notion, and Obsidian.
50+
- **Review before you remember.** Captures from connected sources land in a Review inbox, grouped into at
51+
most fifteen decisions, where you approve, edit, or archive. Approving records the memory and its audit
52+
event in SQLite, then mirrors it to your Markdown vault. Files you import yourself are treated as trusted
53+
and are usable right away; pass `auto_approve=false` to route them through Review too.
54+
- **Ask and get citations or nothing.** Retrieval fuses BM25, `sqlite-vec` vector KNN, and temporal
55+
signals, reranks on-device, and passes through a cite-or-abstain gate. With no cited evidence it tells
56+
you so rather than guessing.
57+
- **Connect your tools in one click.** Claude Desktop, Cursor, Windsurf, Zed, Cline, Roo Code, VS Code
58+
Copilot, and Claude Code get a Cortex MCP server written into their config.
59+
- **Keep control.** Per-tool tokens are scoped and revocable, secret/email redaction is on by default,
60+
and export, maintenance, and destructive capabilities are **off** until you enable them.
61+
62+
Ask composes its answers deterministically from cited excerpts — no generative language model is
63+
bundled or called to write prose. Retrieval embeddings run entirely on-device.
64+
65+
### Current limitations, plainly
66+
67+
- **Apple Silicon, macOS 13+.** The Swift target is `arm64-apple-macosx13.0`; there is no Intel or
68+
universal build.
69+
- **This beta requires a one-time account sign-in.** The shipped build sets `CortexRequireAccount`, so
70+
first launch shows a sign-in wall. Your memory still lives and is queried locally — the account is
71+
identity plus an optional sync target. There is an "Explore with sample notes" path, but it is not
72+
remembered between launches.
73+
- **Cloud sync is not end-to-end encrypted by default.** Client-side E2EE exists but is opt-in and off,
74+
so anything you sync is readable server-side. See [`docs/E2EE_SYNC_DESIGN.md`](docs/E2EE_SYNC_DESIGN.md).
75+
- **Managed Google / Microsoft / Notion OAuth is implemented but not configured** in this build; those
76+
client IDs ship empty. Use file import or a pasted token instead.
77+
- **PDF text extraction is inactive** in the shipped app — `pypdf` is not bundled.
3878

3979
| Stop repeating yourself | Keep memory trustworthy | Switch tools freely | Inspect everything |
4080
|---|---|---|---|
@@ -412,7 +452,7 @@ file and focused test for a change.
412452
| Sync & encryption | [`docs/E2EE_SYNC_DESIGN.md`](docs/E2EE_SYNC_DESIGN.md) · [`docs/CXE1_WIRE_FORMAT.md`](docs/CXE1_WIRE_FORMAT.md) |
413453
| Install & update checks | [`docs/INSTALLER_AND_UPDATES.md`](docs/INSTALLER_AND_UPDATES.md) |
414454
| Release & distribution | [`docs/DISTRIBUTION.md`](docs/DISTRIBUTION.md) · [`docs/APPLE_RELEASE.md`](docs/APPLE_RELEASE.md) |
415-
| Experimental pairwise twin evaluation | [Overview](https://github.com/trace-cortex/cortex-app/blob/feat/pairwise-twin-eval/docs/PAIRWISE_TWIN_EVALUATION.md) · [Integration guide](https://github.com/trace-cortex/cortex-app/blob/feat/pairwise-twin-eval/docs/PAIRWISE_TWIN_INTEGRATION_GUIDE.md) |
455+
| Experimental pairwise twin evaluation | [`docs/PAIRWISE_TWIN_EVALUATION.md`](docs/PAIRWISE_TWIN_EVALUATION.md) · [`docs/PAIRWISE_TWIN_INTEGRATION_GUIDE.md`](docs/PAIRWISE_TWIN_INTEGRATION_GUIDE.md) |
416456

417457
## Build with us
418458

‎backend/app/config.py‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
from __future__ import annotations
22

3+
import math
34
import os
45
from dataclasses import dataclass
56
from pathlib import Path
@@ -51,6 +52,13 @@ class Settings:
5152
store_cache_size: int = 512
5253
rate_limit_per_minute: int = 0
5354
default_memory_quota: int = 0
55+
pairwise_preflight_max_provider_calls: int = 1_000
56+
pairwise_preflight_max_total_tokens: int = 10_000_000
57+
pairwise_preflight_max_duration_seconds: float = 86_400
58+
pairwise_preflight_max_parallel_generations: int = 1
59+
pairwise_preflight_max_parallel_judgments: int = 1
60+
pairwise_admission_signing_key: str = ""
61+
pairwise_admission_receipt_ttl_seconds: int = 15 * 60
5462
require_scoped_api_tokens: bool = False
5563
sync_signing_key: str = ""
5664
hosted_database_url: str = ""
@@ -192,6 +200,22 @@ def _truthy_env(name: str) -> bool:
192200
return os.environ.get(name, "").strip().lower() in {"1", "true", "yes", "on"}
193201

194202

203+
def _positive_int_env(name: str, default: int) -> int:
204+
try:
205+
value = int(os.environ.get(name, str(default)) or str(default))
206+
except (TypeError, ValueError):
207+
return default
208+
return value if value > 0 else default
209+
210+
211+
def _positive_float_env(name: str, default: float) -> float:
212+
try:
213+
value = float(os.environ.get(name, str(default)) or str(default))
214+
except (TypeError, ValueError):
215+
return default
216+
return value if math.isfinite(value) and value > 0 else default
217+
218+
195219
def _load_plan_quotas() -> dict[str, int] | None:
196220
"""Parse CORTEX_PLAN_QUOTAS (JSON object mapping plan name -> int quota).
197221
Malformed input falls back to the baked-in defaults so a bad env can never
@@ -269,6 +293,37 @@ def load_settings() -> Settings:
269293
store_cache_size=max(1, int(os.environ.get("CORTEX_STORE_CACHE_SIZE", "512") or "512")),
270294
rate_limit_per_minute=max(0, int(os.environ.get("CORTEX_RATE_LIMIT_PER_MINUTE", "0") or "0")),
271295
default_memory_quota=max(0, int(os.environ.get("CORTEX_DEFAULT_MEMORY_QUOTA", "0") or "0")),
296+
pairwise_preflight_max_provider_calls=_positive_int_env(
297+
"CORTEX_PAIRWISE_MAX_PROVIDER_CALLS",
298+
1_000,
299+
),
300+
pairwise_preflight_max_total_tokens=_positive_int_env(
301+
"CORTEX_PAIRWISE_MAX_TOTAL_TOKENS",
302+
10_000_000,
303+
),
304+
pairwise_preflight_max_duration_seconds=_positive_float_env(
305+
"CORTEX_PAIRWISE_MAX_DURATION_SECONDS",
306+
86_400,
307+
),
308+
pairwise_preflight_max_parallel_generations=_positive_int_env(
309+
"CORTEX_PAIRWISE_MAX_PARALLEL_GENERATIONS",
310+
1,
311+
),
312+
pairwise_preflight_max_parallel_judgments=_positive_int_env(
313+
"CORTEX_PAIRWISE_MAX_PARALLEL_JUDGMENTS",
314+
1,
315+
),
316+
pairwise_admission_signing_key=os.environ.get(
317+
"CORTEX_PAIRWISE_ADMISSION_SIGNING_KEY",
318+
"",
319+
),
320+
pairwise_admission_receipt_ttl_seconds=min(
321+
_positive_int_env(
322+
"CORTEX_PAIRWISE_ADMISSION_RECEIPT_TTL_SECONDS",
323+
15 * 60,
324+
),
325+
60 * 60,
326+
),
272327
require_scoped_api_tokens=require_scoped_api_tokens,
273328
sync_signing_key=os.environ.get("CORTEX_SYNC_SIGNING_KEY", ""),
274329
hosted_database_url=os.environ.get("CORTEX_HOSTED_DATABASE_URL", os.environ.get("DATABASE_URL", "")).strip(),

‎backend/app/connectors/notion.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
from dataclasses import dataclass
44
import json
55
import re
6-
from typing import Any, Callable
6+
from typing import Any, Callable, Optional
77
from urllib.parse import urlencode
88
from urllib.request import Request
99

@@ -20,7 +20,7 @@
2020
MAX_BLOCK_TREE_DEPTH = 3
2121

2222

23-
RequestJSON = Callable[[str, dict[str, str], dict[str, Any] | None, str], Any]
23+
RequestJSON = Callable[[str, dict[str, str], Optional[dict[str, Any]], str], Any]
2424

2525

2626
@dataclass(frozen=True)

0 commit comments

Comments
 (0)