Spaces:
Running
Running
| title: StockAnalysis | |
| emoji: 📊 | |
| colorFrom: pink | |
| colorTo: gray | |
| sdk: gradio | |
| sdk_version: 6.30.0 | |
| python_version: '3.13' | |
| app_file: app.py | |
| pinned: false | |
| license: mit | |
| short_description: Structured stock analysis as JSON for agents. | |
| suggested_hardware: cpu-basic | |
| tags: | |
| - stock-analysis | |
| - finance | |
| - agents | |
| - gradio | |
| - huggingface-hub | |
| - inference-providers | |
| - smoke-test | |
| - model-evaluation | |
| models: | |
| - Qwen/Qwen3.8-27B | |
| - Qwen/Qwen3.8-Flash-Next | |
| - meta-models/Muse-Spark-Open-816B-A42B | |
| - reflection/Beam-1.0-501B-A23B | |
| - deepseek-ai/DeepSeek-V4.1-Flash | |
| - meta-llama/Meta-Llama-3-8B-Instruct | |
| - nvidia/NVIDIA-Nemotron-3.5-Super-VL-120B-A12B-NVFP4 | |
| - moonshotai/Kimi-K3 | |
| - zai-org/GLM-5.3-Flash | |
| - meta-llama/Llama-3.1-8B-Instruct | |
| - meta-models/Muse-Spark-Open-816B-A42B-NVFP4 | |
| - OBLITERATUS/Qwen3.8-27B-OBLITERATED | |
| - zai-org/GLM-5.3 | |
| - meta-models/Muse-Glimmer-30B | |
| - google/gemma-4-31B-it | |
| - Qwen/Qwen3.5-9B | |
| - meta-llama/Llama-3.2-3B-Instruct | |
| - XiaomiMiMo/MiMo-V2.6-Pro-RL | |
| - inclusionAI/Ling-3.1-flash | |
| - Qwen/Qwen3.5-4B | |
| - openai/gpt-oss-20b | |
| - google/gemma-4-26B-A4B-it | |
| - Qwen/Qwen3.6-35B-A3B | |
| - huihui-ai/Huihui-Qwen3.8-27B-abliterated | |
| - openai/gpt-oss-120b | |
| - XiaomiMiMo/MiMo-V2.6-Flash-RL | |
| - Qwen/Qwen2.5-1.5B-Instruct | |
| - Qwen/Qwen3-0.6B | |
| - Qwen/Qwen3-8B | |
| - deepseek-ai/DeepSeek-R1 | |
| # StockAnalysis | |
| StockAnalysis returns stock-analysis output as JSON for humans and agents. | |
| The main screen collects a ticker, horizon, risk profile, and an optional | |
| question. The Space sends that request to a separate stock-analysis project and | |
| returns the upstream result as JSON, with the raw response kept beside it. If | |
| the upstream project returns text, an optional local model can convert it to | |
| JSON without inventing prices, targets, or recommendations. | |
| The original inference smoke test is still here. It now lives in a compact panel | |
| fixed to the bottom-right corner of the page, with the live model table, run | |
| history, JSON download, and settings. | |
| ## Agent API | |
| There is no separate REST layer. Agents call the normal Gradio event behind the | |
| **Analyze** button. The Hub also generates a live `agents.md` for the Space. The | |
| repository copy at [`agents.md`](./agents.md) adds concrete examples. | |
| ```text | |
| To use this application (igardner/StockAnalysis: Structured stock analysis as JSON for agents): | |
| API schema: GET https://igardner-stockanalysis.hf.space/gradio_api/info | |
| Call endpoint: POST https://igardner-stockanalysis.hf.space/gradio_api/call/v2/analyze {"ticker": "AAPL", "horizon": "3 months", "risk_profile": "balanced", "question": ""} | |
| Poll result: GET https://igardner-stockanalysis.hf.space/gradio_api/call/analyze/{event_id} | |
| File inputs: none - all inputs are JSON scalars. | |
| Auth: Bearer $HF_TOKEN (https://huggingface.co/settings/tokens) | |
| ``` | |
| The endpoint returns three values in order: the JSON result, the raw upstream | |
| response, and a short human-readable status string. The JSON result is the value | |
| agents should use. See [`agents.md`](./agents.md) for the full boundary and | |
| promise list, error shapes, retry guidance, and the private smoke-test caveat. | |
| ```bash | |
| EVENT_ID=$(curl -sS -X POST \ | |
| "https://igardner-stockanalysis.hf.space/gradio_api/call/v2/analyze" \ | |
| -H "Content-Type: application/json" \ | |
| -H "Authorization: Bearer $HF_TOKEN" \ | |
| -d '{"ticker":"AAPL","horizon":"3 months","risk_profile":"balanced","question":""}' \ | |
| | python -c 'import json,sys; print(json.load(sys.stdin)["event_id"])') | |
| curl -sS -N \ | |
| "https://igardner-stockanalysis.hf.space/gradio_api/call/analyze/$EVENT_ID" \ | |
| -H "Authorization: Bearer $HF_TOKEN" | |
| ``` | |
| Always fetch `/gradio_api/info` before calling. The schema is the runtime | |
| contract, and Gradio can change the generated examples between versions. | |
| ## Configuration | |
| | Variable | Required | Default | Purpose | | |
| |---|---|---|---| | |
| | `EXTERNAL_API_URL` | for real results | blank | HTTP endpoint of the external stock-analysis project. | | |
| | `STOCK_MODEL_ID` | no | blank | Uploaded custom model ID. Sent as `model` when set. | | |
| | `LOCAL_PARSER_URL` | no | blank | OpenAI-compatible chat endpoint used to convert text to JSON. | | |
| | `LOCAL_PARSER_MODEL` | no | `llama3.1` | Model name for the local parser. | | |
| | `HF_TOKEN` | for smoke test and private calls | Space secret | Token read with `os.getenv("HF_TOKEN")`. Never committed. | | |
| `EXTERNAL_API_URL` is blank until the external project is ready. Until it is | |
| set, the app returns a clear `not_configured` JSON response instead of failing | |
| silently. `STOCK_MODEL_ID` is also blank until the custom model is uploaded. | |
| Add `HF_TOKEN` under **Settings → Variables and secrets → New secret** in the | |
| Space. Secrets are injected as environment variables and are write-only in the | |
| UI. Restart the Space after adding or changing one. The app never writes the | |
| token to disk or into run results. | |
| ## Custom model | |
| The custom stock-analysis model is not wired in yet. Set `STOCK_MODEL_ID` to its | |
| Hub model ID (or to whatever identifier the external project expects) when it is | |
| ready. If it is blank, the external request omits the `model` field. | |
| ## Local JSON parser | |
| The parser is optional. It is useful when the external project returns text but | |
| an agent needs JSON. It calls any OpenAI-compatible chat-completions endpoint and | |
| asks the model to preserve the source facts. | |
| With Ollama: | |
| ```bash | |
| ollama serve | |
| ollama pull llama3.1 | |
| export LOCAL_PARSER_URL=http://127.0.0.1:11434/v1 | |
| export LOCAL_PARSER_MODEL=llama3.1 | |
| ``` | |
| The app also accepts a full `/chat/completions` URL. A base URL ending in `/v1` | |
| works, and a bare host gets `/v1/chat/completions` appended. | |
| On Hugging Face Spaces, `127.0.0.1` points at the Space container. Use a | |
| reachable parser endpoint or a Docker Space with a sidecar if you want the local | |
| parser to run next to the app. The normal deployment path is the external | |
| project plus its own JSON output. | |
| ## External project contract | |
| The adapter in `external_api.py` sends: | |
| ```json | |
| { | |
| "ticker": "AAPL", | |
| "horizon": "3 months", | |
| "risk_profile": "balanced", | |
| "question": "" | |
| } | |
| ``` | |
| It adds `"model": "<STOCK_MODEL_ID>"` when a custom model is configured. It | |
| sends `Authorization: Bearer $HF_TOKEN` when the secret is present. | |
| Response handling: | |
| - HTTP 2xx with JSON: passed through unchanged. | |
| - HTTP 2xx with text: wrapped as `{"status": "ok", "ticker": "...", "raw": "..."}` | |
| unless the local parser is configured. | |
| - Non-2xx: returned as `{"status": "error", ...}` with the HTTP status and a | |
| short error message. | |
| - No `EXTERNAL_API_URL`: returned as `{"status": "not_configured", ...}`. | |
| The adapter is the only place to change when the external request or response | |
| contract changes. | |
| ## Inference smoke test | |
| The smoke test is still the original liveness check. It queries the Hub for the | |
| most trending conversational models with a live inference provider, sends one | |
| tiny chat completion to each, and records a literal `True` or `False`. The | |
| compact bottom-right panel shows the model table, run history, download, and | |
| settings. | |
| The smoke-test events are marked `api_visibility="private"`, so they do not | |
| appear in the public API docs or the Gradio clients. Private does not block | |
| direct HTTP, so it is not a security boundary. The Analyze event is the only | |
| public endpoint. | |
| Settings live at the top of `app.py`: | |
| ```python | |
| MODEL_LIMIT = 30 # how many trending models to test | |
| CONCURRENCY = 3 # parallel requests | |
| MAX_TOKENS = 8 # output tokens per attempt | |
| REQUEST_TIMEOUT_SECONDS = 60 # per-request timeout | |
| RESULTS_DIR = "/data/hf-inference-smoke" | |
| PAGE_SIZE = 100 # Hub discovery page size | |
| MAX_SCAN = 500 # how far past MODEL_LIMIT to scan | |
| AUTO_RUN_ON_START = False # run automatically on page load | |
| ``` | |
| Every run is saved to persistent storage, not the repository: | |
| ```text | |
| /data/hf-inference-smoke/ | |
| ├── latest.json # most recent run (mirror) | |
| ├── runs/<run_id>.json # one file per run | |
| └── models/latest.json # most recent discovery snapshot | |
| ``` | |
| Each run file records the model list, trending scores, live providers, | |
| per-attempt status, latency, usage, and errors. | |
| ### Models used | |
| The list below is the last recorded snapshot, kept so the tested models and the | |
| smoke-test history are not lost. Selection is dynamic, so the next run can use a | |
| different order. The run JSON always records the exact list it used. | |
| Snapshot: `2026-10-25T20:18:59Z` | |
| Last recorded run: `20261025T202058Z-ff6262` at `2026-10-25T20:20:58Z` - **21/30 passed** in 64.56s. | |
| | # | Model | Result | | |
| |---:|---|---| | |
| | 1 | `Qwen/Qwen3.8-27B` | True | | |
| | 2 | `Qwen/Qwen3.8-Flash-Next` | False | | |
| | 3 | `meta-models/Muse-Spark-Open-816B-A42B` | True | | |
| | 4 | `reflection/Beam-1.0-501B-A23B` | True | | |
| | 5 | `deepseek-ai/DeepSeek-V4.1-Flash` | True | | |
| | 6 | `meta-llama/Meta-Llama-3-8B-Instruct` | False | | |
| | 7 | `nvidia/NVIDIA-Nemotron-3.5-Super-VL-120B-A12B-NVFP4` | True | | |
| | 8 | `moonshotai/Kimi-K3` | True | | |
| | 9 | `zai-org/GLM-5.3-Flash` | True | | |
| | 10 | `meta-llama/Llama-3.1-8B-Instruct` | True | | |
| | 11 | `meta-models/Muse-Spark-Open-816B-A42B-NVFP4` | False | | |
| | 12 | `OBLITERATUS/Qwen3.8-27B-OBLITERATED` | False | | |
| | 13 | `zai-org/GLM-5.3` | True | | |
| | 14 | `meta-models/Muse-Glimmer-30B` | True | | |
| | 15 | `google/gemma-4-31B-it` | True | | |
| | 16 | `Qwen/Qwen3.5-9B` | True | | |
| | 17 | `meta-llama/Llama-3.2-3B-Instruct` | False | | |
| | 18 | `XiaomiMiMo/MiMo-V2.6-Pro-RL` | True | | |
| | 19 | `inclusionAI/Ling-3.1-flash` | True | | |
| | 20 | `Qwen/Qwen3.5-4B` | False | | |
| | 21 | `openai/gpt-oss-20b` | True | | |
| | 22 | `google/gemma-4-26B-A4B-it` | True | | |
| | 23 | `Qwen/Qwen3.6-35B-A3B` | True | | |
| | 24 | `huihui-ai/Huihui-Qwen3.8-27B-abliterated` | False | | |
| | 25 | `openai/gpt-oss-120b` | True | | |
| | 26 | `XiaomiMiMo/MiMo-V2.6-Flash-RL` | True | | |
| | 27 | `Qwen/Qwen2.5-1.5B-Instruct` | False | | |
| | 28 | `Qwen/Qwen3-0.6B` | False | | |
| | 29 | `Qwen/Qwen3-8B` | True | | |
| | 30 | `deepseek-ai/DeepSeek-R1` | True | | |
| ### How the smoke test works | |
| 1. Discovery queries the Hub for `conversational` models sorted by | |
| `trendingScore`, scanning past the requested count so models without a live | |
| inference provider are skipped. | |
| 2. Routing calls each model through the HF router with `:cheapest`. If that | |
| fails, it retries once with `:fastest`. | |
| 3. A model passes only when the router returns HTTP 200 with a non-empty | |
| `choices` array. | |
| 4. Each attempt asks for at most 8 output tokens, so a 30-model run costs well | |
| under a cent. | |
| 5. Every run is saved to `/data/hf-inference-smoke/`. | |
| A `False` result means the model could not produce a valid chat completion | |
| through either routing policy at the time of the run. It is a liveness check, not | |
| a quality benchmark. | |
| ## Claims and disclaimer | |
| The app is built for structured stock analysis and predictions. It does not | |
| promise a specific return, and it does not guarantee that any result will be | |
| profitable. Output comes from an external project and may be incomplete or | |
| wrong. | |
| This is research tooling, not financial advice. Markets involve risk, including | |
| loss of principal. Verify anything before acting on it. | |
| ## Project layout | |
| ```text | |
| app.py # Gradio UI, settings, public /analyze event, smoke corner | |
| external_api.py # external stock-analysis project adapter | |
| local_parser.py # optional OpenAI-compatible text-to-JSON converter | |
| smoke.py # discovery, routing, smoke runner, persistence | |
| agents.md # concrete agent contract and examples | |
| PROGRESS.md # implementation notes, committed as work proceeds | |
| requirements.txt # pinned dependencies | |
| README.md # Space metadata and documentation | |
| ``` | |
| ## Requirements | |
| - Python 3.13 and Gradio 6.30.0 via the README `sdk_version`. | |
| - `huggingface_hub==1.16.1` and `requests==2.34.2` pinned in | |
| `requirements.txt`. | |
| - CPU basic hardware is sufficient. No GPU is required. | |
| - `HF_TOKEN` should be a Space secret for the smoke test and authenticated | |
| outbound calls. | |
| ## Deployment | |
| 1. Add `HF_TOKEN` as a Space secret. | |
| 2. Set `EXTERNAL_API_URL` when the external stock-analysis project is ready. | |
| 3. Set `STOCK_MODEL_ID` when the custom model is uploaded. | |
| 4. Optionally set `LOCAL_PARSER_URL` and `LOCAL_PARSER_MODEL` for text-to-JSON | |
| conversion. | |
| 5. Restart the Space. | |
| After restart, `GET /gradio_api/info` lists the `analyze` endpoint. The smoke | |
| test remains available in the bottom-right corner and does not appear in the | |
| public endpoint list. | |
| ### Maintainer note: dev mode | |
| If the Space is in dev mode, pushed commits do not trigger a rebuild. Do not | |
| disable dev mode or run a factory reboot on a live dev container; that tears down | |
| the running environment. Use the dev-mode workflow to apply changes, or restart | |
| the Space intentionally after the dev session is finished. | |