Yassir

Open-source AI agent for halal finance — predictive Shariah compliance, not just screening.

Don't just screen. Catch compliance drift before it hits your portfolio. Yassir plans the research, calls the right HalalTerminal tools, and delivers decision-ready answers — including trajectory, staleness, and replacement insights you didn't have to ask for.

Quickstart  |   What it does  |   Core Workflows  |   Shariah Screening  |   For AI Agents  |   LLM Providers  |   Self-hosting  |   Contributing

---

What's new in 2.0 — Predictive Compliance

• Insights endpoints, wired in. Three new tools — get_compliance_trajectory, get_screening_staleness, get_halal_alternatives — turn Yassir from a screener into a watchdog. Surfaces ratio drift before a name flips, flags stale screens against recent SEC filings, and suggests halal replacements for non-compliant holdings.
• /monitor, /trajectory, /staleness. New slash commands run the predictive trio across a single name, a watchlist, or an arbitrary symbol set. Single decision-grade table out: verdict · trajectory · staleness · alternatives if needed.
• Honest ETF verdicts. When the backend exposes v2 disposition (compliant_with_purification, mostly_compliant, non_compliant) and scholar attestations, Yassir surfaces them with that nuance instead of forcing a boolean. ETFs still on the legacy v1 shape continue to render correctly.
• Honest stock verdicts. Scholar-verified methodologies are labeled. ADR currency-mismatch abstains as INSUFFICIENT_DATA instead of forcing wrong answers. Insights endpoints' 200+note degradation is surfaced verbatim, not silently dropped.
• Self-hoster QoL. Key usage tracking (daily burn, recent calls, projected exhaustion), key rotation, and key revocation. Two retries with exponential backoff on 429.
• Evidence-quality discipline in the agent prompt. Yassir distinguishes "no data" from "non-compliant", surfaces degraded sources once at the top, and recommends force_refresh re-screens when staleness fires.

See CHANGELOG.md for the full list.

---

Why Yassir?

Most financial AI tools are either closed-source, limited to chat, or lack real data access. Yassir is different:

• Predictive, not just reactive -- Catches drift toward non-compliance before a name flips, with trajectory, staleness, and alternatives insights wired into the agent's default behavior.
• Autonomous research -- Ask a question, Yassir builds a plan, calls the right tools in sequence, and synthesizes a sourced answer. No manual prompt chaining.
• Real data, not hallucinations -- Pulls from HalalTerminal, SEC EDGAR/open-data tools, and web search fallback. Every important claim can be grounded in tool output.
• Honest verdicts -- Scholar-verified methodologies are labeled. Abstains are abstains, not silent failures. ETFs surface disposition + attestations, not boolean halal/not-halal.
• Shariah-first -- Built around Shariah screening, portfolio audit, purification, watchlist monitoring, and halal replacement workflows.
• CLI first, web second -- The terminal is the primary product surface. The web UI is a companion interface for the same workflows.
• Your LLM, your data -- Runs locally or self-hosted. Supports OpenAI, Anthropic, Google, xAI, DeepSeek, OpenRouter, Moonshot, and Ollama.
• Built for developers -- TypeScript, Apache-2.0 licensed, extensible tool system, and clear product boundaries around HalalTerminal.

---

Quickstart

1. Install

git clone https://github.com/goww7/yassir-oss.git
cd yassir-oss
bun install
cp env.example .env

Add two keys to .env:

OPENAI_API_KEY=sk-proj-...
HALAL_TERMINAL_API_KEY=ht_...

Get a free HalalTerminal key from api.halalterminal.com.

2. Run the CLI

bun dev

3. Run the web app

bun run web:install
bun run web:dev
bun run web:ui

• API server: http://localhost:3000
• Web UI: http://localhost:5173

For hosted web access, set YASSIR_ACCESS_CODE before exposing the app.

4. Try these queries

> Is Apple Shariah-compliant? Show the full screening breakdown.

> /audit AAPL MSFT SPUS

> /purification AAPL MSFT

> /ideas replace QQQ with halal alternatives

> What did Tesla report in their latest 10-K filing? Summarize the risk factors.

Or use Docker

git clone https://github.com/goww7/yassir-oss.git && cd yassir-oss
cp env.example .env
docker compose up --build

Web API at http://localhost:3000.

For AI agents

Yassir includes LLM-friendly project context:

• llms.txt for quick AI discovery and repository orientation
• AGENTS.md for coding-agent guidance
• docs/examples.md for copy-paste research prompts

What users need

• An LLM key, usually OPENAI_API_KEY
• A HalalTerminal key, HALAL_TERMINAL_API_KEY
• Optional search key for richer fallback research

Everything else is optional. Yassir will route between HalalTerminal, SEC/open data, web search, and local workspace tools automatically.

---

What can Yassir do?

Yassir runs a ReAct agent loop: it plans research steps, executes tools, observes results, and iterates until it has a complete answer.

Tools

Tool	Description
get_shariah	HalalTerminal-powered Shariah screening, audits, purification, watchlists, quota, and plans
get_financials	HalalTerminal asset profiles, database records, quotes, dividend history, and SEC XBRL facts
get_market_data	HalalTerminal stock quotes, OHLC history, batch quotes, trending assets, and news
read_filings	Extract and analyze SEC 10-K/10-Q filings
stock_screener	HalalTerminal database search by ticker, name, sector, country, exchange, or asset type
web_search	Federated search across Exa, Tavily, Perplexity, and Brave
x_search	X/Twitter sentiment and market chatter
sec_company_facts	SEC EDGAR structured company data
sec_submissions	SEC filing history and submission metadata
browser	Playwright automation for JS-rendered pages
memory_*	Persistent memory across sessions
skill	Specialist Shariah workflows and other dynamic skills
read_file / write_file	Workspace file operations

Agent features

• Research planning -- generates a focused plan before deep work
• Progress synthesis -- periodic "so far" updates during long runs
• Context management -- automatic clearing when context fills, with scratchpad retrieval
• Persistent memory -- remembers facts across sessions
• Tool approval -- asks before executing sensitive operations
• Quota-aware behavior -- if upstream screening is unavailable, Yassir marks the result as unresolved instead of overstating certainty

---

Core Workflows

Yassir is organized around explicit Shariah-investing workflows instead of a generic multi-profile UX.

Single Asset Review

/screen MSFT
/brief HLAL

Outputs:

• Verdict
• Methodology Breakdown
• Key Reasons
• Purification
• Next Checks

Portfolio Audit

/audit AAPL MSFT SPUS
/portfolio AAPL AMZN TSLA

Outputs:

• Portfolio Verdict
• Compliant / At Risk / Unresolved Holdings
• Concentration Risks
• Recommended Actions

Purification Planner

/purification AAPL MSFT

Outputs:

• Available purification data
• Uncertainty and missing inputs
• What to track next

Predictive Watch (new in 2.0)

/monitor AAPL MSFT NVDA
/monitor watchlist:Halal Tech
/trajectory MSFT
/staleness NVDA

Outputs:

• Single decision-grade table per symbol: verdict · trajectory direction · staleness flag · alternatives if needed
• Compliance drift surfaced from XBRL ratio history
• Stale-screening flags driven by recent 10-K/10-Q/8-K filings
• Ranked halal replacements for any name flagged or already non-compliant

Replacement Ideas

/ideas TSLA
/ideas replace QQQ with halal alternatives

Outputs:

• Target exposure
• Ranked replacement candidates (via get_halal_alternatives for single symbols)
• Trade-offs, methodology coverage, abstain warnings

Guided Workflows

Use /guide to open guided Shariah workflows in CLI or web.

Available flows:

• Single-Asset Review
• Portfolio Audit
• Purification Planner
• Watchlist Monitor
• Replacement Ideas

---

Shariah Screening

Yassir is powered by HalalTerminal for Shariah compliance data and Islamic finance workflows.

Get your API key at api.halalterminal.com.

What's included

• Stock and ETF Shariah screening
• Portfolio scans and audits
• Bulk index screening
• Purification workflows
• Watchlist management and monitoring
• Usage, quota, and plan checks

Source order

Yassir follows this source order:

1. HalalTerminal structured domain data
2. Finance and open-data tools
3. SEC and issuer disclosures where relevant
4. Web search only as fallback or supporting context

Quota handling

If upstream screening is unavailable:

• Yassir marks the result as unresolved
• avoids presenting blocked or partial screening as authoritative
• asks the user to retry once screening access is available again

---

Commands

/screen <symbol>
/compare <a> <b> [c d e]
/portfolio <symbols...>
/audit <symbols...>
/purification <symbols...>
/bulk <index>
/report <symbol>
/brief <symbol>
/monitor <watchlist:name|symbols...>
/trajectory <symbol>
/staleness <symbol>
/ideas <symbol|theme>
/watchlist list
/watchlist create <name>: <symbols...>
/usage
/guide
/workspace
/attach
/keys
/doctor

---

LLM Providers

Use any provider and switch at runtime with /model.

Provider	Environment Variable	Notes
OpenAI	OPENAI_API_KEY	Default
Anthropic	ANTHROPIC_API_KEY	Claude models
Google	GOOGLE_API_KEY	Gemini models
xAI	XAI_API_KEY	Grok models
DeepSeek	DEEPSEEK_API_KEY	Cost-effective alternative
OpenRouter	OPENROUTER_API_KEY	Access many models through one key
Moonshot	MOONSHOT_API_KEY
Ollama	OLLAMA_BASE_URL	Local models

---

Self-hosting

Yassir is designed to be self-hosted.

services:
  yassir:
    build: .
    ports:
      - "3000:3000"
    env_file: .env
    volumes:
      - yassir-data:/app/.yassir
      - yassir-agents:/app/.agents

Set YASSIR_ACCESS_CODE in .env to protect the web UI when hosting it.

Public Deployment Checklist

• Set YASSIR_ACCESS_CODE to a strong shared access code.
• Put Yassir behind HTTPS with a reverse proxy.
• Keep .env out of git and rotate keys if exposed.
• Mount .agents and .yassir as persistent volumes.
• Start with trusted users before opening public signups.
• Review uploaded workspace files before sharing an instance with untrusted users.

---

Configuration

Required

• OPENAI_API_KEY or another supported LLM key
• HALAL_TERMINAL_API_KEY

Recommended

• YASSIR_ACCESS_CODE for hosted web UI protection
• one search provider for richer fallback research:
  • BRAVE_SEARCH_API_KEY
  • EXASEARCH_API_KEY
  • TAVILY_API_KEY
  • PERPLEXITY_API_KEY
  • X_BEARER_TOKEN for X/Twitter context

Agent tuning

• YASSIR_DEFAULT_MODEL
• YASSIR_DEFAULT_PROVIDER
• YASSIR_MAX_ITERATIONS

---

Project Structure

src/
  agent/               ReAct loop, prompt policy, scratchpad, progress
  integrations/        HalalTerminal integration boundary
  profile/             Product profile and guided workflow definitions
  skills/              Specialist Shariah workflows
  tools/finance/       HalalTerminal, market, financials, filings
  web/                 Hono API server
web/
  src/                 React companion UI

---

Development

bun run typecheck
bun test

If you touch the web UI:

bun run web:install
bun run web:build

Contributing

See CONTRIBUTING.md.

Learn more

• Research library
• Halal Terminal blog
• What is Islamic finance?
• Sukuk screening guide
• API reference

Part of the Halal Terminal ecosystem

Website · API · Python SDK · JS SDK · MCP server · Claude plugin · Discord bot · TradingView indicator · Portfolio tracker

Related projects

Other open-source tools in the HalalTerminal ecosystem — same API, different surfaces:

Project	What it is	License
halal-discord-bot	Discord bot — /halal AAPL, /portfolio, /trending slash commands for Shariah-compliant screening	MIT
halal-portfolio-tracker	Next.js 14 app — enter your holdings, get per-stock compliance + portfolio halal % + purification owed. One-click Vercel deploy.	MIT
halal-pine	TradingView Pine Script v5 indicator that overlays compliance status on charts. Refreshed daily from the API.	MIT
halalterminal-mcp	MCP server — connect Cursor, Cline, Codex, or any MCP-compatible client to the HalalTerminal API.	Apache-2.0
halalterminal-claude-skills	Claude Code plugin — Shariah screening skills usable directly from your terminal AI.	MIT

License

Apache License 2.0. See NOTICE for HalalTerminal attribution.

---

Built with HalalTerminal