🔐 TrustFlow AI

A full-stack AI agent system combining a local LLM (via Ollama), real-time web search (Tavily), an x402-style payment simulation layer, and ERC-8004 blockchain decision logging — all wrapped in a Streamlit chat interface.

---

Architecture

Project Structure:

trustflow-ai/
├── backend/
│   ├── __init__.py           # Package marker
│   ├── config.py             # Centralised env-var configuration
│   ├── logger.py             # Structured JSON logger
│   ├── llm.py                # Ollama REST client (local LLM)
│   ├── search.py             # Tavily web-search client
│   ├── payment.py            # x402-style payment simulation layer
│   ├── agent.py              # ReAct orchestrator (LLM + search + payment + blockchain)
│   └── services/
│       └── blockchain.py     # ERC-8004 decision logging & on-chain verification
├── frontend/
│   └── app.py               # Streamlit UI (Chat + Trust Ledger tabs)
├── contracts/
│   ├── TrustLedger.sol      # Smart contract for on-chain decision storage
│   └── deploy.js             # Hardhat deployment script
├── logs/                    # JSON log output (git-ignored)
├── .env.example             # Environment variable template
├── .gitignore
├── requirements.txt
└── README.md

System Flow:

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│   Frontend   │────▶│  Agent       │────▶│  Ollama (LLM)   │
│  (Streamlit) │     │  Orchestrator │     └─────────────────┘
└─────────────┘     └──────┬───────┘
                           │
                    ┌──────▼───────┐     ┌─────────────────┐
                    │  Decision    │────▶│  Tavily Search  │
                    │  Logger      │     └─────────────────┘
                    └──────┬───────┘
                           │
                    ┌──────▼───────┐     ┌─────────────────┐
                    │  Blockchain  │────▶│  ERC-8004       │
                    │  Service     │     │  TrustLedger    │
                    └──────────────┘     └─────────────────┘

---

Components

backend/llm.py — Ollama Integration

Wraps Ollama's /api/chat endpoint for local LLM inference.

• Supports multi-turn conversation via message history
• Auto-detects available local models
• Raises ConnectionError with a clear message if Ollama is not running

backend/search.py — Tavily Search

Calls the Tavily Search API for real-time web results.

• Falls back to mock results when no API key is set (safe for local dev)
• format_for_context() serialises results into LLM-ready text

backend/payment.py — x402 Payment Layer

Simulates the HTTP 402 Payment Required micropayment pattern.

• Each Wallet has a credit balance and an immutable transaction ledger
• wallet.authorize(cost) — deducts credits or raises PaymentRequiredError
• wallet.top_up() — adds credits (simulates settlement)
• Costs are configurable via .env

backend/agent.py — ReAct Orchestrator

Implements a Reason → Act loop with blockchain decision logging:

1. User message appended to conversation history
2. LLM decides: {"action": "search", "query": "…"} or {"action": "answer", "content": "…"}
3. If search: Tavily is called, results injected into context, loop continues
4. If answer: final response returned with full thought trace
5. Payment gated at every LLM call and every search call
6. Every answer logs a decision hash to the blockchain (ERC-8004 identity)

backend/services/blockchain.py — ERC-8004 Identity & Decision Logging

Logs every AI decision on Ethereum with verifiable identity.

• Computes SHA-256 hash of (decision_id, agent_id, input, output, reasoning, timestamp)
• Stores hash locally (mock mode) or on Ethereum testnet
• Links each decision to an ERC-8004-style agent identity
• Falls back to mock mode when blockchain is not configured

frontend/app.py — Streamlit UI

• Chat interface with message history and thought traces
• Trust Ledger tab — decision history with on-chain verification badges
• Sidebar wallet dashboard (live balance, top-up, transaction ledger)
• Expandable thought trace and search result panels per response
• Ollama / Tavily / Blockchain status indicators

---

Prerequisites

Requirement	Version	Notes
Python	3.10+
Ollama	latest	Must be running locally
Ollama model	any	e.g. ollama pull llama3
Tavily API key	—	Optional — free tier available
Ethereum RPC	—	Optional — for on-chain logging

---

Quick Start

1. Clone

git clone https://github.com/joshuapremkumar/trustflow-ai.git
cd trustflow-ai

2. Configure

cp .env.example .env
# Edit .env — add your TAVILY_API_KEY and ETHEREUM_RPC_URL (optional)

3. Start Ollama

ollama serve          # start the Ollama daemon
ollama pull llama3    # pull your chosen model

4. Run

Windows:

streamlit run frontend/app.py

macOS / Linux:

streamlit run frontend/app.py

Open http://localhost:8501 in your browser.

---

Configuration Reference

Variable	Default	Description
OLLAMA_BASE_URL	http://localhost:11434	Ollama server URL
OLLAMA_DEFAULT_MODEL	llama3	Local model name
TAVILY_API_KEY	(empty)	Tavily API key (optional)
TAVILY_MAX_RESULTS	5	Max search results per query
PAYMENT_INITIAL_CREDITS	10.0	Starting wallet balance
PAYMENT_LLM_COST	0.05	Credits per LLM call
PAYMENT_SEARCH_COST	0.10	Credits per search call
PAYMENT_TOPUP_AMOUNT	5.0	Credits added per top-up
ETHEREUM_RPC_URL	(empty)	Ethereum RPC URL (optional)
ETHEREUM_PRIVATE_KEY	(empty)	Wallet private key (optional)
ETHEREUM_CONTRACT_ADDRESS	(empty)	Deployed contract (optional)
AGENT_ID	trustflow-erc8004-001	ERC-8004 agent identity
LOG_LEVEL	INFO	Logging verbosity

---

Payment Flow (x402-style)

User sends message
         │
         ▼
  wallet.authorize(LLM_COST)  ──── insufficient? ──► HTTP 402 analogue
         │
         ▼
  Ollama LLM call
         │
         ├─ action: "search"
         │       │
         │       ▼
         │  wallet.authorize(SEARCH_COST)  ──── insufficient? ──► 402
         │       │
         │       ▼
         │  Tavily search → inject results → loop back to LLM
         │
         └─ action: "answer"
                 │
                 ▼
          wallet.authorize(BLOCKCHAIN_LOG_COST)
                 │
                 ▼
          Log decision with SHA-256 hash (ERC-8004 identity)
                 │
                 ▼
           Return AgentResponse (answer + trace + blockchain record)

---

Blockchain & ERC-8004 Identity

How It Works

Every AI decision generates a verifiable hash containing:

• Decision ID (unique identifier)
• Agent ID (ERC-8004 identity: trustflow-erc8004-001)
• Input query
• Output response
• Reasoning trace
• Timestamp

The hash is:

1. Stored locally — always available in mock mode
2. Optionally on-chain — stored on Ethereum Sepolia testnet

Deployment Modes

Mock Mode (Default): Decisions logged locally with hash verification

ETHEREUM_RPC_URL=

On-Chain Mode: Real blockchain storage

ETHEREUM_RPC_URL=https://sepolia.infura.io/v3/YOUR_PROJECT_ID
ETHEREUM_PRIVATE_KEY=your_private_key
ETHEREUM_CONTRACT_ADDRESS=deployed_contract_address

Deploy Smart Contract

cd contracts
npm install
npx hardhat compile
npx hardhat run scripts/deploy.js --network sepolia

---

Trust Ledger

The Trust Ledger tab shows:

• Total decisions logged
• On-chain vs mock count
• Decision history with verification status
• Transaction hashes for on-chain records
• SHA-256 hash verification

---

Logging

All modules write structured JSON logs to logs/<module>.log:

{"timestamp": "2026-03-22T10:00:00Z", "level": "INFO", "module": "blockchain", "message": "Decision logged: abc123 (on_chain=False)"}

---

Extending the Agent

To add new tools:

1. Create backend/tools/<tool>.py with a run(input) -> str interface
2. Add a new action shape to the system prompt in agent.py
3. Handle the new action in the TrustFlowAgent.run() loop
4. Add a cost constant in payment.py

---

License

MIT

---

Built with 🔐 TrustFlow AI · Powered by Ollama + Tavily + Streamlit + Ethereum