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.

Yassir in action

Yassir research output

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:

HalalTerminal structured domain data
Finance and open-data tools
SEC and issuer disclosures where relevant
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

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

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

Yassir

What's new in 2.0 — Predictive Compliance

Why Yassir?

Quickstart

1. Install

2. Run the CLI

3. Run the web app

4. Try these queries

Or use Docker

For AI agents

What users need

What can Yassir do?

Tools

Agent features

Core Workflows

Single Asset Review

Portfolio Audit

Purification Planner

Predictive Watch (new in 2.0)

Replacement Ideas

Guided Workflows

Shariah Screening

What's included

Source order

Quota handling

Commands

LLM Providers

Self-hosting

Public Deployment Checklist

Configuration

Required

Recommended

Agent tuning

Project Structure

Development

Contributing

Learn more

Part of the Halal Terminal ecosystem

Related projects

License

Yorumlar (0)