Metadata-Version: 2.4
Name: astos
Version: 0.6.0
Summary: ASTOS — Abstract Syntax Tree Observer Service. Mapa do repo + queries com teto de tokens para debug rápido de IAs; 3D offline para humanos.
Author: ASTOS
License: MIT
Project-URL: Homepage, https://github.com/HonoravelMacho/astos
Project-URL: Repository, https://github.com/HonoravelMacho/astos
Keywords: ast,graph,3d,three.js,webgl,cli,visualization
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Environment :: Console
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Dynamic: license-file

# astos

**A code-map for AI agents.** astos scans your repository into a dependency
graph once, then answers the questions your AI agent keeps burning tokens
on — cheaply, with file+line citations.

```
$ astos debug
ASTOS debug :: 12 arquivo(s) sujo(s) no git — ordem de leitura (entrypoints: astos/cli.py):
- astos/cli.py [M] +106/-26 deg=6 · quem chama: `tests/test_cli.py`:11 ...
- astos/queries.py [M] +214/-35 deg=6 · chama: astos/parser.py:118
```

| | |
|---|---|
| ![](docs/img/debug.gif) | ![](docs/img/orbit.gif) |

*Left: real terminal output, verbatim. Right: the offline 3D map of astos
itself.*

## The proof (measured, reproducible)

Same bug-hunt question, same repo, same answer — 10× less context fed to the
agent. Repo: [psf/requests](https://github.com/psf/requests) @ `611c616`
(200 files). Question: *"where does the user-configured timeout actually get
applied?"* Answer: `src/requests/adapters.py :: HTTPAdapter.send`
(`TimeoutSauce` at line 684). Both policies find it.

| policy | bytes into context | ~tokens | how |
|---|---:|---:|---|
| grep + read 3 files whole | 72,168 | 18,042 | grep output (2.9KB) + full `adapters.py`, `sessions.py`, `api.py` |
| astos | 7,215 | 1,804 | AGENTS.md block (1.5KB — free context) + `q --symbol` (0.5KB) + `trace` (0.7KB) + **only the target def** (4.5KB) |

**10.0× less context, identical answer.** Tokens estimated at bytes/4 (the
standard proxy). The naive policy is the deterministic grep-and-read pattern
agents use without a map; astos's side counts every byte an agent would see.
Reproduce it yourself:

```bash
pip install astos
python3 bench/benchmark.py   # clones requests, scans, measures, saves results.json
```

## Quickstart

```bash
pip install astos
astos          # full scan → .astos/ (3D map + graph) + AGENTS.md block
astos -f       # fast refresh (mtime cache; no browser)
astos debug    # where's the bug? dirty files ranked, with callers at line N
```

That's it. Open the `.astos/index.html` (works 100% offline, no server) or
let your agent read `AGENTS.md` — the block there is maintained
automatically and is the cheapest context your agent will ever get.

## What your agent gets

`AGENTS.md` gains a surgically-maintained block: file map, dependencies,
hubs, risks, capabilities, entry points. Then 14 queries answer the rest
without re-reading source:

| query | what it answers (cheaply) |
|---|---|
| `astos debug` | which dirty files matter first, who breaks, at which line |
| `astos q --symbol NAME` | where NAME lives (file:line) + cap hits |
| `astos trace --from A --to B` | all paths/hops between two modules |
| `astos impact --file F` | who calls F and what F calls — **with call-site lines** |
| `astos hubs` / `astos risks` | god-files, dead files, TODO/FIXME density, cap files |
| `astos dead` | files unreachable from any entrypoint |
| `astos q --cap camera` | who touches the camera (file + evidence, incl. manifests) |
| `astos slice <dir>` | a local sub-map for one folder |
| `astos changed` | delta since last commit, as a graph |

There's also an **MCP server** (`astos mcp --path .`) exposing the same
queries as agent tools — no shell needed.

## Capabilities: who talks to which hardware

25 capability categories detected from real code APIs, manifests and
dependency files: `camera`, `microphone`, `location`, `bluetooth`,
`usb`, `serial`, `gpio`, `i2c`, `spi`, `keyboard`, `gamepad`,
`vibration`, `sms`, `contacts`, `health`, `motion`, `biometrics`, `nfc`,
`telephony`, `sensors`, `storage`, `notifications`, `screen`, `media`,
`network`.

```bash
$ astos q --cap camera
ASTOS q :: 1 hit(s) (ordenado por grau)
- `app.py` deg=0 lang=python caps=camera
manifest: `manifest:AndroidManifest.xml[CAMERA]`
```

Sources it reads: AndroidManifest.xml permissions, iOS Info.plist
(`NS*UsageDescription`), UWP `.appxmanifest`, `package.json` /
`Cargo.toml` / `go.mod` / `pubspec.yaml` / Gradle / Podfile dependency
names — plus API usage inside code (e.g. `cv2.VideoCapture`,
`navigator.serial`, `SensorManager`, `input.location`). `stdio`-noise control: docstrings and comments don't count as usage; a
"camera dictionary" file that merely mentions every capability gets
filtered out by density.

## How it works

- 13 language parsers (Python, JS/TS, Dart, Kotlin, Java, Go, Rust, C/C++,
  C#, PHP, Ruby, Swift, generic) — pure stdlib; **no tree-sitter, no LSP**.
- Call edges are heuristic (name matching) — good enough to rank, cited
  with the exact call-site line so the agent can verify.
- Incremental cache: `astos -f` re-scans only changed files (mtime+size).

## For this repo's own contributors

```bash
pip install -e . && pip install pytest
python3 -m pytest            # 46 tests
bench/benchmark.py           # measure token savings yourself
bench/make_gifs.py           # regenerate docs/img/*.gif
```

*PT-BR: [README.pt-BR.md](README.pt-BR.md)*

## License

MIT
