InnerTrace

InnerTrace is a privacy-aware personal context intelligence engine. It connects user-provided journals, browser history, screen-time logs, sleep records, steps, and calendar events into a unified timeline, then produces traceable observations with evidence and confidence.

It is designed as a portfolio-grade demonstration of data ingestion, normalization, deterministic analysis, optional retrieval-augmented generation (RAG), structured LLM output, safety controls, and interactive data visualization.

What you can demo in 3 minutes

1. Load the fictional Alex dataset.
2. Build a unified timeline from journals, sleep, screen time, browser history, calendar events, and steps.
3. Generate local evidence-backed insight cards without an API key.
4. Open the evidence drawer to inspect event IDs, quotes, metrics, and confidence reasons.
5. Review privacy controls and reset all local data.

Why this project is sharper than a generic dashboard

InnerTrace is built around evidence infrastructure rather than model polish alone. The core product loop is a repeatable weekly review: inspect patterns, verify provenance, correct weak or inaccurate claims, and turn useful findings into small experiments. The AI layer is optional. The durable value is transparent analysis, human correction, and relative change against a personal baseline.

Product framing

Target users: privacy-conscious self-trackers, creators, researchers, founders, graduate students, and remote workers who already collect fragmented personal data.

Problem: personal context is distributed across incompatible exports. Individual records rarely explain how routines and events relate over time.

What InnerTrace does:

• accepts CSV, JSON, TXT, Markdown, and PDF;
• detects journal, sleep, screen-time, browser, calendar, and step data;
• normalizes sources into one chronological event model;
• generates fully local, deterministic pattern insights;
• optionally indexes text-rich events in Chroma with OpenAI embeddings;
• optionally runs an auditable LangGraph RAG workflow;
• attaches evidence, time range, confidence, limitations, and safety notes;
• lets the user delete one source or reset all local data.
• supports Daily Check-ins and deterministic Weekly Reviews;
• compares recent signals with a 14-day personal baseline;
• records human feedback, saved patterns, and seven-day experiments;
• exposes privacy modes and source-level analysis controls;
• includes export-based connector adapters and a synthetic evaluation suite.

What InnerTrace does not do: diagnose, confirm, or predict medical or mental health conditions; provide medication or treatment advice; infer facts that are not supported by uploaded evidence.

Optional AI configuration

InnerTrace runs without OPENAI_API_KEY. In local rule-based mode, sample loading, uploads, parsing, timeline building, rule-based insights, the dashboard, privacy center, deletion, and reset remain available.

Without a key, /index, /search, /insights/llm, and /insights/graph return HTTP 503 with:

AI-powered RAG and LLM insights require an OpenAI API key. Rule-based insights are still available.

An OpenAI key is optional and is used only for embeddings, vector search, RAG, and LLM-generated insights. Create your own key and store it locally:

cd backend
cp .env.example .env
# Edit backend/.env and replace the placeholder value.

Never commit .env. It is excluded by .gitignore, and no API key is returned to or logged by the frontend.

Technical stack

• Frontend: Next.js, React, TypeScript, Tailwind foundation, custom responsive CSS
• Visualization: Recharts and D3.js
• Backend: FastAPI, Python, Pydantic
• Analysis: pandas and deterministic pattern detectors
• Parsing: pypdf, pandas, native text/JSON parsers
• AI, optional: OpenAI embeddings and structured Responses API
• Retrieval: local persistent Chroma
• Orchestration: LangGraph
• Storage: local uploads, JSON timeline, local Chroma collection
• Testing: pytest, FastAPI TestClient, Next.js production build

System architecture

flowchart LR
    UI["Next.js dashboard"] --> API["FastAPI"]
    API --> FILES["Local uploads"]
    FILES --> PARSE["Typed parsers"]
    PARSE --> TIME["Unified TimelineEvent"]
    TIME --> RULES["Rule-based detectors"]
    RULES --> CARDS["InsightCard + evidence + confidence"]

    TIME --> INDEX["OpenAI embeddings (optional)"]
    INDEX --> CHROMA["Local Chroma"]
    CHROMA --> RAG["RAG retrieval"]
    RAG --> GRAPH["LangGraph workflow"]
    RULES --> GRAPH
    GRAPH --> LLM["Structured LLM output"]
    LLM --> SAFE["Confidence + safety validation"]
    SAFE --> CARDS

Loading

LangGraph workflow

flowchart TD
    A["Load and filter timeline"] --> B["Check query and timeline safety"]
    B --> C["Retrieve relevant context"]
    C --> D["Run deterministic pattern detectors"]
    D --> E["Generate structured LLM insights"]
    E --> F["Canonicalize evidence IDs"]
    F --> G["Regrade confidence"]
    G --> H["Rewrite or remove unsafe claims"]
    H --> I["Return validated InsightCard list"]

Loading

There is no route from model generation to the API response that bypasses evidence canonicalization, confidence grading, and the final safety filter.

Data model

ParsedDocument preserves the source file and either structured rows or raw text. TimelineEvent provides a common event shape:

event_id, timestamp, end_timestamp, source_file_id, source_type,
event_type, title, content, metrics, metadata

Every InsightCard includes:

insight_id, title, summary, pattern_type, time_range, data_sources,
evidence[], confidence_level, confidence_score, confidence_reason,
recommended_reflection_questions[], safety_note

Evidence references canonical timeline event_id values and includes a source type, timestamp, quote or named metric, and explanation.

Confidence scoring

The backend recalculates confidence after generation. It considers evidence count, distinct source types, time span, traceable quotes/metrics, and deterministic effect strength.

• low: below 0.45
• medium: 0.45 to below 0.75
• high: 0.75 or above

Confidence means evidence coverage and traceability. It does not represent medical certainty or causality.

Recurring product loop

Daily Check-ins add user-entered energy, workload, and context to the local timeline. Weekly Review summarizes the latest seven days through five fixed questions: repeated pressure themes, sleep/screen changes, common features of high-output days, available evidence about low-energy days, and one small adjustment to test.

Insights support a human-in-the-loop Action Loop:

• Save as pattern creates durable, user-controlled memory.
• Mark inaccurate suppresses the same deterministic finding in future runs.
• Turn into experiment creates a seven-day hypothesis, actions, and measures.
• Additional feedback supports accurate, partially accurate, sensitive/hide, use in future, and do-not-use-source states.

The Personal Baseline reports 14-day sleep, screen-time, steps, repeated topics, and late-night activity. These are descriptive comparisons with the user’s own available history.

Connector adapters

The connector layer uses explicit exports rather than live account permissions:

• Google Calendar export
• Chrome history export
• Apple Health normalized export
• Screen Time CSV
• Notion Markdown export
• Google Takeout normalized export

Each adapter has a synthetic import for demo purposes. Real OAuth, HealthKit, and mobile permissions are intentionally outside this portfolio phase.

Privacy and safety

• Files and the vector database are stored locally.
• The frontend receives capability status, never secret values.
• Rule-based analysis does not call an external AI service.
• OpenAI receives relevant text only when the user configures a key and invokes AI features.
• Diagnostic, medication, unsupported certainty, therapy-like, and crisis-language checks are enforced.
• Generated evidence IDs are validated against canonical timeline events.
• Users can delete one source or reset uploads, timeline, and Chroma.
• The included Alex dataset is fictional and contains no real personal data or crisis content.

More detail: privacy-and-safety.md.

Local setup

Prerequisites: Python 3.11–3.13 and Node.js 20+.

Backend:

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload

API: http://localhost:8000
OpenAPI docs: http://localhost:8000/docs

Frontend, in a second terminal:

cd frontend
npm install
npm run dev

Dashboard: http://localhost:3000

Docker:

docker compose up --build

Docker also runs without a key. To enable optional AI behavior, set OPENAI_API_KEY in the local shell before starting Compose.

Demo instructions

The fastest UI flow is Run Alex demo. It loads six sample files, parses them, builds the timeline, and:

• returns local rule-based insights when no API key exists;
• indexes the timeline and runs the RAG/LangGraph flow when AI is configured.

API-only rule-based demo:

curl http://localhost:8000/demo/load
curl -X POST http://localhost:8000/timeline/build
curl -X POST http://localhost:8000/insights/rule-based

Complete optional AI demo:

curl -X POST http://localhost:8000/insights/demo

Reset:

curl -X POST http://localhost:8000/reset

See demo-script.md for a three-minute walkthrough.

API endpoints

Method	Route	Purpose	API key
GET	/health	Service health	No
GET	/config/status	Safe AI capability status	No
POST	/upload	Store a supported file	No
GET	/files	List local sources	No
DELETE	/files/{file_id}	Delete source and related events	No
POST	/parse/{file_id}	Parse and detect source type	No
POST	/timeline/build	Build normalized timeline	No
GET	/timeline	Read/filter timeline	No
POST	/insights/rule-based	Local deterministic insights	No
POST	/index	Embed and index text events	Yes
POST	/search	Semantic search	Yes
POST	/insights/llm	Structured LLM synthesis	Yes
POST	/insights/graph	Complete LangGraph workflow	Yes
GET	/demo/load	Idempotently load Alex sample	No
GET	/demo/status	Demo pipeline status	No
POST	/insights/demo	AI pipeline or safe rule fallback	Optional
POST	/reset	Clear local uploads/timeline/index	No
POST / GET	/check-ins	Add or list Daily Check-ins	No
GET	/reviews/weekly	Generate a local Weekly Review	No
GET	/baseline	Calculate personal baseline	No
POST	/insights/{id}/feedback	Record human feedback	No
POST / GET	/patterns	Save or list Pattern Library entries	No
POST / GET	/experiments	Create or list behavior experiments	No
GET / PUT	/privacy	Read or update privacy controls	No
GET	/connectors	List export adapters	No
POST	/connectors/{id}/sample-import	Import synthetic adapter data	No

Testing

cd backend
source .venv/bin/activate
pytest -q

cd ../frontend
npm run build

cd ..
backend/.venv/bin/python evals/run_evals.py

Tests cover parsing, normalization, pattern detection, confidence, safety, insight validation, optional-AI route guards, rule-based demo output, baselines, reviews, deletion, and reset. The eval suite measures evidence coverage, evidence traceability, diagnostic-language safety, confidence consistency, and expected pattern recall.

Screenshots

Dashboard overview

Evidence drawer

Privacy center

Theme network

Documentation

• Product thinking
• System design
• Privacy and safety
• Data schema
• RAG and LangGraph
• Three-minute demo script
• Evaluation

Future roadmap

1. Encrypted local profiles and explicit per-source consent.
2. Incremental indexing and source-level vector deletion.
3. Evaluation datasets for retrieval quality, evidence fidelity, and safety regressions.
4. Time-window comparison and user-controlled hypothesis feedback.
5. Local embedding/model option for a fully offline AI mode.
6. Exportable evidence reports and interoperable data connectors.