agents.md

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)

# StockAnalysis agent contract

This file is the concrete contract for agents. The Hub also generates a live
`agents.md` at `https://huggingface.co/spaces/igardner/StockAnalysis/agents.md`.
Always fetch `/gradio_api/info` before calling. The live schema is the runtime
contract; this file explains the boundaries and the expected response shapes.

## What this Space does

- Accepts a ticker, horizon, risk profile, and optional question.
- Sends that request to a separate stock-analysis project.
- Returns three outputs in order: JSON, the raw upstream body, and a short
  human-readable status string.
- If the upstream returns text and a local parser is configured, converts that
  text to JSON without inventing prices, targets, or recommendations.

The Analyze request is read-only. It does not place trades, move funds, or
connect to a brokerage account.

## Boundaries: what this Space will not do

- It is not financial advice and is not a substitute for a licensed advisor.
- It does not guarantee returns, accuracy, completeness, availability, or
  latency. Do not represent it as promising 10x gains or any other return.
- It does not execute trades or manage money.
- It does not verify the external project's claims or data.
- It does not provide personalized advice. Treat output as research material
  that a human reviews.
- It does not accept file inputs. Do not call `/gradio_api/upload`.
- It does not expose the smoke test as part of the agent contract. The smoke
  test events are marked private; do not call them.
- It does not promise uptime. This is a CPU-basic Space and can sleep, restart,
  or be rebuilt.
- It does not intentionally persist Analyze requests. The external project may
  have its own retention policy.

## Promises: what agents can rely on

- When the Gradio call completes, it returns exactly three outputs in this
  order: JSON result, raw upstream body, status string.
- The first output is JSON-serializable. Error and configuration failures are
  returned as JSON objects instead of a successful-looking analysis.
- Expected failures use these `status` values: `not_configured`,
  `invalid_input`, or `error`. A text-to-JSON wrapper uses `status: "ok"` plus
  `source: "external+local_parser"`.
- An upstream JSON response is passed through unchanged. Its shape is defined by
  the external project, not by this Space.
- Missing or empty tickers return `invalid_input`. Unknown horizon or risk
  values are coerced to `3 months` and `balanced`.
- The Space never returns `HF_TOKEN` or any server secret in its outputs.
- Private smoke-test outputs are not part of the Analyze response.

## Inputs

| Name | Type | Required | Default | Rules |
|---|---|---|---|---|
| `ticker` | string | yes | none | Uppercased and trimmed. Maximum 24 characters. Empty is rejected. |
| `horizon` | string | no | `3 months` | `1 week`, `1 month`, `3 months`, `6 months`, or `1 year`. Unknown values become `3 months`. |
| `risk_profile` | string | no | `balanced` | `conservative`, `balanced`, or `aggressive`. Unknown values become `balanced`. |
| `question` | string | no | empty | Optional. Truncated to 2000 characters. Do not put secrets or personal data here. |

There are no file inputs.

## Outputs

1. JSON result. Read this first.
2. Raw upstream response as text. May be empty.
3. Human-readable status string. Do not parse this as machine data.

The JSON result can be one of these shapes:

- Upstream JSON, passed through unchanged.
- `{"status": "ok", "ticker": "...", "http_status": 200, "content_type": "...", "raw": "..."}`
  when the upstream returned text and no parser was configured.
- `{"status": "ok", "ticker": "...", "source": "external+local_parser", "parser": {"model": "..."}, "analysis": <JSON>, "raw": "..."}`
  when the local parser succeeded.
- `{"status": "not_configured", "message": "..."}` when `EXTERNAL_API_URL` is
  unset.
- `{"status": "invalid_input", "error": "..."}` for bad input.
- `{"status": "error", "http_status": ..., "error": "...", "raw": "..."}` for
  upstream failures.
- The text-wrapper shape plus `parse_error` when the local parser failed.

Check for the `status` field before treating a result as analysis. Our error
envelopes include `ticker` and an `error` or `message` field. Upstream JSON is
not wrapped, so its own fields are whatever the external project returns.

## Call with curl

```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"
```

The POST returns `{"event_id": "..."}`. The GET streams Server-Sent Events. The
final event is `complete` and its `data` field is the three-element output list.
An `error` event means the call failed; a stream that ends without `complete`
should be treated as a failure.

If a client only supports the older call shape, send the same inputs as a
positional list to `/gradio_api/call/analyze`:

```json
{"data": ["AAPL", "3 months", "balanced", ""]}
```

## Call with the Python client

```python
import os
from gradio_client import Client

client = Client("igardner/StockAnalysis", token=os.environ["HF_TOKEN"])
result = client.predict(
    "AAPL",
    "3 months",
    "balanced",
    "",
    api_name="/analyze",
)
print(result)
```

## Error handling and retries

- Check the JSON result's `status` before using any analysis fields.
- Do not retry `invalid_input` or `not_configured`. Fix the input or ask the
  Space owner to set `EXTERNAL_API_URL`.
- For HTTP 429, 5xx, network errors, or a stream without `complete`, retry with
  exponential backoff and a small retry cap (for example, three attempts).
  Honor `Retry-After` when it is present.
- Do not retry a `parse_error` blindly. The raw upstream body is still in the
  second output, so use that if your client can parse it.
- The server allows up to four concurrent Analyze events. Stay below that, and
  do not flood the Space with parallel requests.

## Auth and data handling

- Send `Authorization: Bearer $HF_TOKEN` on both the POST and the poll GET.
- Never put the token in the JSON body, the `question` field, or a URL query
  string.
- `HF_TOKEN` is for Space authentication and rate limits. The Space's own
  outbound token is a Space secret and is never returned to clients.
- The ticker and question are sent to the external project. Do not send
  secrets, credentials, or personal data.
- The Space does not intentionally store Analyze requests. The external project
  may log or retain them under its own policy.

## Discovery and versioning

- Fetch `GET /gradio_api/info` at the start of a session. Do not hardcode
  parameter names, return counts, or endpoint paths beyond the documented
  fallback.
- The live `/agents.md` route is generated by Hugging Face from Space metadata.
  This repository copy is documentation, not a replacement for the live schema.
- The external project and the custom model can change independently. The custom
  model is configured with `STOCK_MODEL_ID` and is currently blank.

## Disclaimer

This is research tooling, not financial advice. Output may be incomplete or
wrong. No return is guaranteed, and you can lose money. Nothing in this contract
promises a specific gain, including 10x.