cyberagent 0.1.0__tar.gz

cyberagent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 K.C
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cyberagent-0.1.0/PKG-INFO

@@ -0,0 +1,340 @@
+Metadata-Version: 2.4
+Name: cyberagent
+Version: 0.1.0
+Summary: Physical-bottleneck, reverse-consensus investment analysis for every market — an LLM agent chain that traces any asset (A-share / HK / US stocks, crypto) to its supply-chain constraint and refuses to chase narrative-driven tops. Bring your own LLM key.
+Author-email: CyberK13 <klchen0113@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/CyberK13/cyberagent
+Project-URL: Source, https://github.com/CyberK13/cyberagent
+Project-URL: Documentation, https://github.com/CyberK13/cyberagent#readme
+Project-URL: Issues, https://github.com/CyberK13/cyberagent/issues
+Project-URL: Changelog, https://github.com/CyberK13/cyberagent/blob/main/CHANGELOG.md
+Keywords: ai-agent,llm,equity-analysis,stock-analysis,crypto-analysis,multi-agent,langchain,crewai,mcp,chain-of-thought,investment-research,quantitative-finance
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<3.0,>=2.0
+Requires-Dist: httpx>=0.25
+Provides-Extra: stocks
+Requires-Dist: yfinance>=0.2; extra == "stocks"
+Provides-Extra: web
+Requires-Dist: flask>=3.0; extra == "web"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: gemini
+Requires-Dist: google-genai>=0.2; extra == "gemini"
+Provides-Extra: claude
+Requires-Dist: anthropic>=0.8; extra == "claude"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Provides-Extra: all
+Requires-Dist: yfinance>=0.2; extra == "all"
+Requires-Dist: flask>=3.0; extra == "all"
+Requires-Dist: openai>=1.0; extra == "all"
+Requires-Dist: google-genai>=0.2; extra == "all"
+Requires-Dist: anthropic>=0.8; extra == "all"
+Dynamic: license-file
+
+<div align="center">
+
+# 🧠 cyberagent
+
+### Physical-bottleneck, reverse-consensus investment analysis — for *every* market
+
+A chain of LLM agents that traces any asset down to the **physical constraint**
+that caps its industry, checks whether the market has **already priced it**, and
+**refuses to chase a narrative-driven top**. Stocks (A-share / HK / US) and
+crypto (token / contract). Bring your own LLM key.
+
+[![PyPI](https://img.shields.io/pypi/v/cyberagent.svg)](https://pypi.org/project/cyberagent/)
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+### 🌐 Language / 语言
+
+**English** &nbsp;|&nbsp; [简体中文](README.zh.md)
+
+</div>
+
+---
+
+> 🚧 **Early release.** The analysis engine works end-to-end today; the
+> public API may still evolve before `1.0`.
+
+---
+
+## What makes it different
+
+Most open-source "AI analyst" frameworks ask *"is this a good company?"* and
+return a textbook SWOT. cyberagent asks a sharper, **falsifiable, reverse-consensus**
+question, in a fixed order:
+
+> **Physical bottleneck → uniqueness → commercialization → financial elasticity → consensus correction**
+>
+> *Where is the physical constraint in this asset's supply chain? Is it unique?
+> Can it be monetized? Does it have non-linear financial elasticity? And has the
+> market already priced it in?*
+
+It is built on one idea from Leopold Aschenbrenner's *[Situational Awareness](https://situational-awareness.ai/)*:
+**AI scaling is a massive *industrial* process**, bottlenecked by physical inputs —
+power, transformers, HBM, CoWoS packaging, specific materials. cyberagent
+operationalizes that thesis: it walks the supply chain down to the link
+*"no amount of money can buy"*, and then applies hard anti-narrative discipline so
+it doesn't mistake a headline-driven spike for an opportunity.
+
+It does **not** predict prices. It produces facts, a falsifiable logic chain, and
+monitorable physical signals — the final decision is yours.
+
+---
+
+## Intellectual foundations
+
+cyberagent stands on two ideas and turns them into a reproducible, falsifiable
+agent chain.
+
+### Leopold Aschenbrenner — *Situational Awareness* (the **why**)
+
+In *[Situational Awareness: The Decade Ahead](https://situational-awareness.ai/)*,
+Aschenbrenner argues that **AI scaling is a massive *industrial* process**, not a
+software one: every frontier model needs a bigger cluster, then bigger power
+plants, then bigger fabs. So the binding limits are **physical** — power,
+transformers, HBM, CoWoS packaging, specific materials — and effective compute
+compounds at roughly an order of magnitude (OOM) per year (GPT‑2 → GPT‑4 → ~2027
+AGI). The people with *situational awareness* build conviction from the trendlines
+**years before consensus prices them**. cyberagent treats the market as that
+physical system; the thesis is distilled in [`references/sa-canon.md`](references/sa-canon.md).
+
+### Serenity & Crux — the bottleneck method (the **how**)
+
+The practitioner discipline comes from supply-chain bottleneck hunters such as
+**Serenity** ([@aleabitoreddit](https://x.com/aleabitoreddit)) and **Crux Capital**.
+Instead of asking *"which stock goes up?"*, they **take the machine apart and look
+for the chokepoint**:
+
+> *What does the machine actually look like? Which part of its BOM is the hardest
+> to replace? If one supplier stopped shipping tomorrow, how long would the whole
+> chain wait?*
+
+- **Serenity** is *narrow and deep* — find one decisive choke point and concentrate.
+- **Crux** is *wide and disciplined* — map a ~6-layer stack and size each layer by execution certainty, separating proven executors from early optionality.
+
+cyberagent distills that discipline into a fixed, falsifiable chain that any LLM
+can run across any market.
+
+> We borrow their **method** — tracing a supply chain to its physical chokepoint,
+> asking *"where does the chain break"*, separating execution from optionality. We
+> do **not** impersonate them, quote them, or present their positions as fact.
+
+---
+
+## How it works
+
+The chain is a **telescope** — it zooms from physical reality down to the specific,
+actionable name, one grounded LLM call per stage (each reads the upstream reports):
+
+> **Positioning → Physical World → Human Development → Economics → Company Financials → Leaders & Verdict**
+
+That telescope is how the five-step *method* above (bottleneck → uniqueness →
+commercialization → elasticity → consensus) actually gets executed.
+
+```mermaid
+flowchart LR
+    IN["Any asset<br/>NVDA · 600519 · 0700 · BTC · 0x…"] --> CL{{AssetClassifier}}
+    CL --> AD["Data adapters<br/>yfinance · CoinGecko · DefiLlama<br/>+ price action + analyst consensus"]
+    AD --> P0["Phase 0 · Positioning<br/>core business → physical-world position"]
+    P0 --> D1[physical] --> D2[human_dev] --> D3[economics] --> D4[financials] --> D5[leaders]
+    D5 --> R["AnalystReport<br/>ACCUMULATE · HOLD · REDUCE · AVOID"]
+```
+
+**Phase 0 — Positioning.** From the fundamentals, lock down what the company
+actually sells, then pin it to a specific layer of the physical / AI supply chain
+(materials → substrate → equipment → packaging → device → module → system → end
+demand) and a concrete machine (e.g. a *GB300 NVL72 rack*, a *1.6T optical link*).
+
+**Five departments**, run in sequence, each reading the upstream reports:
+
+| Dept | `key` | What it does |
+|---|---|---|
+| 🪨 Physical World | `physical` | Locate the binding bottleneck on the SA ladder (power > CoWoS/HBM > raw logic); classify the asset as **owner / adjacent / derivative / none**. Non-owner ⇒ downgraded, scarcity-rent logic forbidden. |
+| 🌍 Human Development | `human_dev` | Place the demand on the AGI / OOM arc — early (runway left) or mature/peaked? |
+| 💱 Economics | `economics` | ore-seller vs processor; **decompose the price move into earnings-growth vs multiple-expansion**; detect valuation-framework switches; is it *already priced* (Gray Rhino vs loud consensus)? |
+| 📈 Company Financials | `financials` | Fundamentals + financial elasticity (linear vs non-linear); attribute earnings anomalies *before* flagging them. |
+| 🎯 Leaders & Verdict | `leaders` | Two-axis verdict — **bottleneck identity (a) vs pricing position (b)** — steelman + Munger inversion, monitorable exit signals, final decision. |
+
+### The discipline (why it won't chase a top)
+
+This is the part textbook frameworks skip:
+
+- **Real-time grounding** — with Gemini it *searches why a price moved* (the catalyst, who said what), instead of trusting model memory.
+- **Price-action guardrail** — the data layer flags parabolic / near-high moves; a stock that doubled in days on one headline is an **AVOID / observe** form, never a buy.
+- **Evidence ladder** — every key claim is tagged `Confirmed / Inferred / Weak`; a load-bearing `Inferred` claim caps the confidence.
+- **Two independent axes** — *"is it a bottleneck"* (classification) and *"should you buy it here"* (pricing) are never conflated. A non-bottleneck can be a fine trade at a price; a real bottleneck at a top can be a bad one.
+- **Honest "too late"** — parabolic move + extreme valuation + loud consensus ⇒ the label is *"too late / top"*, not an opportunity.
+
+> Educational and research use only. Output quality varies with the model, data,
+> and many non-deterministic factors. **This is not financial, investment, or
+> trading advice.**
+
+---
+
+## Quickstart
+
+```python
+import asyncio
+
+from cyberagent import AnalystChain
+
+chain = AnalystChain(llm="gemini", api_key="...", lang="en")  # grounding on by default
+
+report = asyncio.run(chain.analyze("NVDA"))   # US · or 600519 (A-share) / 0700 (HK) / BTC / 0x6B17...
+
+print(report.final_decision)             # ACCUMULATE / HOLD / REDUCE / AVOID
+print(report.confidence)                 # 0.0 - 1.0
+print(report.positioning)                # Phase 0 — core business + physical position
+print(report.departments["physical"].markdown)
+print(report.departments["leaders"].markdown)
+```
+
+(Inside Jupyter or an async app, call `await chain.analyze("NVDA")` directly.)
+
+**One import, any market.** Pick the report language with `lang="zh"` / `"en"`;
+the whole report is generated in it.
+
+---
+
+## Install
+
+```bash
+pip install 'cyberagent[stocks,gemini,web]'   # recommended: stock data + grounded Gemini + local web UI
+```
+
+Extras: **`stocks`** (yfinance) · **`gemini` / `openai` / `claude`** (providers) ·
+**`web`** (local UI) · **`all`** (everything). The bare `pip install cyberagent` is
+the zero-dependency core.
+
+## Set up your API key
+
+cyberagent is **bring-your-own-key**. Gemini is the default and the only provider
+with real-time grounding — recommended.
+
+**1. Get a key** — Gemini is free to start:
+[aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey).
+(Other providers: [OpenAI](https://platform.openai.com/api-keys) ·
+[Anthropic](https://console.anthropic.com/) ·
+[DeepSeek](https://platform.deepseek.com/).)
+
+**2. Configure it** — create a `.env` file in the folder you run from:
+
+```bash
+echo 'GOOGLE_API_KEY=your_key_here' > .env
+```
+
+(All supported variables are listed in [`.env.example`](.env.example).)
+The CLI and web UI auto-load `.env`. In code you can pass it directly instead:
+
+```python
+AnalystChain(llm="gemini", api_key="your_key_here")
+```
+
+**3. Run it** — `cyberagent` (interactive) or `cyberagent serve` (web). The model
+picker shows a ✓ next to every key it found in your `.env`.
+
+## Bring your own LLM key
+
+Gemini is the default (and the only provider with real-time grounding). You can
+also pass any provider or a custom adapter:
+
+```python
+from cyberagent import AnalystChain, LLMAdapter, MockLLM
+
+AnalystChain(llm="gemini",   api_key="...")          # default, grounded
+AnalystChain(llm="openai",   api_key="sk-...")
+AnalystChain(llm="claude",   api_key="...")
+AnalystChain(llm="deepseek", api_key="...")
+AnalystChain(llm=MockLLM())                           # offline, no key — try the flow
+
+class MyLLM(LLMAdapter):
+    async def complete(self, system: str, user: str) -> str: ...
+AnalystChain(llm=MyLLM())
+```
+
+Keys are read from the environment / a local `.env` (see [`.env.example`](.env.example)).
+
+## CLI & local web page
+
+```bash
+cyberagent                                   # interactive: pick language + model, then a symbol
+cyberagent analyze NVDA --llm gemini --lang en
+cyberagent analyze BTC  --depts physical,economics,leaders   # subset, faster
+cyberagent serve                             # local web UI at http://127.0.0.1:8000
+```
+
+The CLI and web page show a model picker that auto-matches the API key found in
+your `.env` (✓ / ✗), live per-department progress, and the rendered report.
+
+---
+
+## Use as a Claude Skill — no install
+
+The whole methodology is also packaged as a self-contained **Claude Skill** in
+[`SKILL.md`](SKILL.md) — it runs the same physical-bottleneck chain in pure-prompt
+form, no Python required. To install it in **Claude Code**:
+
+```bash
+mkdir -p ~/.claude/skills/physical-bottleneck-analyst
+curl -fsSL https://raw.githubusercontent.com/CyberK13/cyberagent/main/SKILL.md \
+  -o ~/.claude/skills/physical-bottleneck-analyst/SKILL.md
+```
+
+Then just ask: *"analyze NVDA"* — Claude picks the skill up automatically. (Any
+other agent that loads skills works the same way: give it `SKILL.md`.) The Python
+package adds live data, real-time grounding, and the CLI / web UI on top.
+
+## Methodology & prompts — fully open
+
+There is no paywall. *How* to hunt a physical bottleneck is framework knowledge,
+not alpha. The complete system prompts live in
+[`src/cyberagent/prompts/departments.py`](src/cyberagent/prompts/departments.py),
+and the *Situational Awareness* anchor (the physical-bottleneck ladder + the OOM
+development arc) is distilled in [`references/sa-canon.md`](references/sa-canon.md).
+
+---
+
+## Roadmap
+
+- [ ] LangChain / LangGraph tool wrapper
+- [ ] MCP server (Claude / Cursor)
+- [ ] EDGAR (US filings) + Tushare (A-share) + Etherscan (EVM) adapters
+- [ ] Segment-level chains for conglomerates
+- [ ] Structured per-department gate verdicts (machine-enforced "stop")
+
+---
+
+## Disclaimer
+
+`final_decision`, `confidence`, and the department reports are **AI-generated
+educational outputs**, not financial advice. LLMs make mistakes; markets are
+unpredictable. Do your own research. The authors and contributors are not liable
+for any decision made based on this software. See [`docs/disclaimer.md`](docs/disclaimer.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+<sub>Publication to the [tea Protocol](https://tea.xyz/) is planned.</sub>

cyberagent-0.1.0/README.md

@@ -0,0 +1,287 @@
+<div align="center">
+
+# 🧠 cyberagent
+
+### Physical-bottleneck, reverse-consensus investment analysis — for *every* market
+
+A chain of LLM agents that traces any asset down to the **physical constraint**
+that caps its industry, checks whether the market has **already priced it**, and
+**refuses to chase a narrative-driven top**. Stocks (A-share / HK / US) and
+crypto (token / contract). Bring your own LLM key.
+
+[![PyPI](https://img.shields.io/pypi/v/cyberagent.svg)](https://pypi.org/project/cyberagent/)
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+### 🌐 Language / 语言
+
+**English** &nbsp;|&nbsp; [简体中文](README.zh.md)
+
+</div>
+
+---
+
+> 🚧 **Early release.** The analysis engine works end-to-end today; the
+> public API may still evolve before `1.0`.
+
+---
+
+## What makes it different
+
+Most open-source "AI analyst" frameworks ask *"is this a good company?"* and
+return a textbook SWOT. cyberagent asks a sharper, **falsifiable, reverse-consensus**
+question, in a fixed order:
+
+> **Physical bottleneck → uniqueness → commercialization → financial elasticity → consensus correction**
+>
+> *Where is the physical constraint in this asset's supply chain? Is it unique?
+> Can it be monetized? Does it have non-linear financial elasticity? And has the
+> market already priced it in?*
+
+It is built on one idea from Leopold Aschenbrenner's *[Situational Awareness](https://situational-awareness.ai/)*:
+**AI scaling is a massive *industrial* process**, bottlenecked by physical inputs —
+power, transformers, HBM, CoWoS packaging, specific materials. cyberagent
+operationalizes that thesis: it walks the supply chain down to the link
+*"no amount of money can buy"*, and then applies hard anti-narrative discipline so
+it doesn't mistake a headline-driven spike for an opportunity.
+
+It does **not** predict prices. It produces facts, a falsifiable logic chain, and
+monitorable physical signals — the final decision is yours.
+
+---
+
+## Intellectual foundations
+
+cyberagent stands on two ideas and turns them into a reproducible, falsifiable
+agent chain.
+
+### Leopold Aschenbrenner — *Situational Awareness* (the **why**)
+
+In *[Situational Awareness: The Decade Ahead](https://situational-awareness.ai/)*,
+Aschenbrenner argues that **AI scaling is a massive *industrial* process**, not a
+software one: every frontier model needs a bigger cluster, then bigger power
+plants, then bigger fabs. So the binding limits are **physical** — power,
+transformers, HBM, CoWoS packaging, specific materials — and effective compute
+compounds at roughly an order of magnitude (OOM) per year (GPT‑2 → GPT‑4 → ~2027
+AGI). The people with *situational awareness* build conviction from the trendlines
+**years before consensus prices them**. cyberagent treats the market as that
+physical system; the thesis is distilled in [`references/sa-canon.md`](references/sa-canon.md).
+
+### Serenity & Crux — the bottleneck method (the **how**)
+
+The practitioner discipline comes from supply-chain bottleneck hunters such as
+**Serenity** ([@aleabitoreddit](https://x.com/aleabitoreddit)) and **Crux Capital**.
+Instead of asking *"which stock goes up?"*, they **take the machine apart and look
+for the chokepoint**:
+
+> *What does the machine actually look like? Which part of its BOM is the hardest
+> to replace? If one supplier stopped shipping tomorrow, how long would the whole
+> chain wait?*
+
+- **Serenity** is *narrow and deep* — find one decisive choke point and concentrate.
+- **Crux** is *wide and disciplined* — map a ~6-layer stack and size each layer by execution certainty, separating proven executors from early optionality.
+
+cyberagent distills that discipline into a fixed, falsifiable chain that any LLM
+can run across any market.
+
+> We borrow their **method** — tracing a supply chain to its physical chokepoint,
+> asking *"where does the chain break"*, separating execution from optionality. We
+> do **not** impersonate them, quote them, or present their positions as fact.
+
+---
+
+## How it works
+
+The chain is a **telescope** — it zooms from physical reality down to the specific,
+actionable name, one grounded LLM call per stage (each reads the upstream reports):
+
+> **Positioning → Physical World → Human Development → Economics → Company Financials → Leaders & Verdict**
+
+That telescope is how the five-step *method* above (bottleneck → uniqueness →
+commercialization → elasticity → consensus) actually gets executed.
+
+```mermaid
+flowchart LR
+    IN["Any asset<br/>NVDA · 600519 · 0700 · BTC · 0x…"] --> CL{{AssetClassifier}}
+    CL --> AD["Data adapters<br/>yfinance · CoinGecko · DefiLlama<br/>+ price action + analyst consensus"]
+    AD --> P0["Phase 0 · Positioning<br/>core business → physical-world position"]
+    P0 --> D1[physical] --> D2[human_dev] --> D3[economics] --> D4[financials] --> D5[leaders]
+    D5 --> R["AnalystReport<br/>ACCUMULATE · HOLD · REDUCE · AVOID"]
+```
+
+**Phase 0 — Positioning.** From the fundamentals, lock down what the company
+actually sells, then pin it to a specific layer of the physical / AI supply chain
+(materials → substrate → equipment → packaging → device → module → system → end
+demand) and a concrete machine (e.g. a *GB300 NVL72 rack*, a *1.6T optical link*).
+
+**Five departments**, run in sequence, each reading the upstream reports:
+
+| Dept | `key` | What it does |
+|---|---|---|
+| 🪨 Physical World | `physical` | Locate the binding bottleneck on the SA ladder (power > CoWoS/HBM > raw logic); classify the asset as **owner / adjacent / derivative / none**. Non-owner ⇒ downgraded, scarcity-rent logic forbidden. |
+| 🌍 Human Development | `human_dev` | Place the demand on the AGI / OOM arc — early (runway left) or mature/peaked? |
+| 💱 Economics | `economics` | ore-seller vs processor; **decompose the price move into earnings-growth vs multiple-expansion**; detect valuation-framework switches; is it *already priced* (Gray Rhino vs loud consensus)? |
+| 📈 Company Financials | `financials` | Fundamentals + financial elasticity (linear vs non-linear); attribute earnings anomalies *before* flagging them. |
+| 🎯 Leaders & Verdict | `leaders` | Two-axis verdict — **bottleneck identity (a) vs pricing position (b)** — steelman + Munger inversion, monitorable exit signals, final decision. |
+
+### The discipline (why it won't chase a top)
+
+This is the part textbook frameworks skip:
+
+- **Real-time grounding** — with Gemini it *searches why a price moved* (the catalyst, who said what), instead of trusting model memory.
+- **Price-action guardrail** — the data layer flags parabolic / near-high moves; a stock that doubled in days on one headline is an **AVOID / observe** form, never a buy.
+- **Evidence ladder** — every key claim is tagged `Confirmed / Inferred / Weak`; a load-bearing `Inferred` claim caps the confidence.
+- **Two independent axes** — *"is it a bottleneck"* (classification) and *"should you buy it here"* (pricing) are never conflated. A non-bottleneck can be a fine trade at a price; a real bottleneck at a top can be a bad one.
+- **Honest "too late"** — parabolic move + extreme valuation + loud consensus ⇒ the label is *"too late / top"*, not an opportunity.
+
+> Educational and research use only. Output quality varies with the model, data,
+> and many non-deterministic factors. **This is not financial, investment, or
+> trading advice.**
+
+---
+
+## Quickstart
+
+```python
+import asyncio
+
+from cyberagent import AnalystChain
+
+chain = AnalystChain(llm="gemini", api_key="...", lang="en")  # grounding on by default
+
+report = asyncio.run(chain.analyze("NVDA"))   # US · or 600519 (A-share) / 0700 (HK) / BTC / 0x6B17...
+
+print(report.final_decision)             # ACCUMULATE / HOLD / REDUCE / AVOID
+print(report.confidence)                 # 0.0 - 1.0
+print(report.positioning)                # Phase 0 — core business + physical position
+print(report.departments["physical"].markdown)
+print(report.departments["leaders"].markdown)
+```
+
+(Inside Jupyter or an async app, call `await chain.analyze("NVDA")` directly.)
+
+**One import, any market.** Pick the report language with `lang="zh"` / `"en"`;
+the whole report is generated in it.
+
+---
+
+## Install
+
+```bash
+pip install 'cyberagent[stocks,gemini,web]'   # recommended: stock data + grounded Gemini + local web UI
+```
+
+Extras: **`stocks`** (yfinance) · **`gemini` / `openai` / `claude`** (providers) ·
+**`web`** (local UI) · **`all`** (everything). The bare `pip install cyberagent` is
+the zero-dependency core.
+
+## Set up your API key
+
+cyberagent is **bring-your-own-key**. Gemini is the default and the only provider
+with real-time grounding — recommended.
+
+**1. Get a key** — Gemini is free to start:
+[aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey).
+(Other providers: [OpenAI](https://platform.openai.com/api-keys) ·
+[Anthropic](https://console.anthropic.com/) ·
+[DeepSeek](https://platform.deepseek.com/).)
+
+**2. Configure it** — create a `.env` file in the folder you run from:
+
+```bash
+echo 'GOOGLE_API_KEY=your_key_here' > .env
+```
+
+(All supported variables are listed in [`.env.example`](.env.example).)
+The CLI and web UI auto-load `.env`. In code you can pass it directly instead:
+
+```python
+AnalystChain(llm="gemini", api_key="your_key_here")
+```
+
+**3. Run it** — `cyberagent` (interactive) or `cyberagent serve` (web). The model
+picker shows a ✓ next to every key it found in your `.env`.
+
+## Bring your own LLM key
+
+Gemini is the default (and the only provider with real-time grounding). You can
+also pass any provider or a custom adapter:
+
+```python
+from cyberagent import AnalystChain, LLMAdapter, MockLLM
+
+AnalystChain(llm="gemini",   api_key="...")          # default, grounded
+AnalystChain(llm="openai",   api_key="sk-...")
+AnalystChain(llm="claude",   api_key="...")
+AnalystChain(llm="deepseek", api_key="...")
+AnalystChain(llm=MockLLM())                           # offline, no key — try the flow
+
+class MyLLM(LLMAdapter):
+    async def complete(self, system: str, user: str) -> str: ...
+AnalystChain(llm=MyLLM())
+```
+
+Keys are read from the environment / a local `.env` (see [`.env.example`](.env.example)).
+
+## CLI & local web page
+
+```bash
+cyberagent                                   # interactive: pick language + model, then a symbol
+cyberagent analyze NVDA --llm gemini --lang en
+cyberagent analyze BTC  --depts physical,economics,leaders   # subset, faster
+cyberagent serve                             # local web UI at http://127.0.0.1:8000
+```
+
+The CLI and web page show a model picker that auto-matches the API key found in
+your `.env` (✓ / ✗), live per-department progress, and the rendered report.
+
+---
+
+## Use as a Claude Skill — no install
+
+The whole methodology is also packaged as a self-contained **Claude Skill** in
+[`SKILL.md`](SKILL.md) — it runs the same physical-bottleneck chain in pure-prompt
+form, no Python required. To install it in **Claude Code**:
+
+```bash
+mkdir -p ~/.claude/skills/physical-bottleneck-analyst
+curl -fsSL https://raw.githubusercontent.com/CyberK13/cyberagent/main/SKILL.md \
+  -o ~/.claude/skills/physical-bottleneck-analyst/SKILL.md
+```
+
+Then just ask: *"analyze NVDA"* — Claude picks the skill up automatically. (Any
+other agent that loads skills works the same way: give it `SKILL.md`.) The Python
+package adds live data, real-time grounding, and the CLI / web UI on top.
+
+## Methodology & prompts — fully open
+
+There is no paywall. *How* to hunt a physical bottleneck is framework knowledge,
+not alpha. The complete system prompts live in
+[`src/cyberagent/prompts/departments.py`](src/cyberagent/prompts/departments.py),
+and the *Situational Awareness* anchor (the physical-bottleneck ladder + the OOM
+development arc) is distilled in [`references/sa-canon.md`](references/sa-canon.md).
+
+---
+
+## Roadmap
+
+- [ ] LangChain / LangGraph tool wrapper
+- [ ] MCP server (Claude / Cursor)
+- [ ] EDGAR (US filings) + Tushare (A-share) + Etherscan (EVM) adapters
+- [ ] Segment-level chains for conglomerates
+- [ ] Structured per-department gate verdicts (machine-enforced "stop")
+
+---
+
+## Disclaimer
+
+`final_decision`, `confidence`, and the department reports are **AI-generated
+educational outputs**, not financial advice. LLMs make mistakes; markets are
+unpredictable. Do your own research. The authors and contributors are not liable
+for any decision made based on this software. See [`docs/disclaimer.md`](docs/disclaimer.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+<sub>Publication to the [tea Protocol](https://tea.xyz/) is planned.</sub>