Hugging Face's logo

Spaces:
Legal-i
/
orgstate
Running

App Files Community
orgstate
File size: 4,985 Bytes
d2d1903
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
# ARCHITECTURE โ€” ืžื‘ื ื” ื”ื™ืขื“

ื”ืžื‘ื ื” ืฉืืœื™ื• ื”โ€‘monorepo ืžืชื›ื ืก. `core/` (+`config`/`calibration`/`pipeline`),
`verticals/logistics/` ื•โ€‘`harness/` ื›ื‘ืจ ื‘ืžื‘ื ื” ื”ื™ืขื“; `infra/` ื•โ€‘`delivery/`
ืขื“ื™ื™ืŸ ื‘โ€‘`legacy/` ื•ืžื”ื’ืจื•ืช ื‘ืฉืœื‘ื™ื ื”ื‘ืื™ื (`MIGRATION_MAP.md`).

## ืขืงืจื•ืŸ ืžื ื—ื”

ืชืœื•ืช ื–ื•ืจืžืช ื‘ื›ื™ื•ื•ืŸ ืื—ื“ ื‘ืœื‘ื“:

```
core  โ†  verticals  โ†  infra  โ†  delivery
 โ–ฒ                                  โ”‚
 โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
        delivery ื•-infra ืžืฉืชืžืฉื™ื ื‘-core; core ืœื ื™ื•ื“ืข ืขืœ ืืฃ ืื—ื“ ืžื”ื
```

`core/` ืืกื•ืจ ืฉื™ึตื“ืข ืขืœ ืฉื•ื ืฉื›ื‘ื” ืื—ืจืช. ืื ืžืฉื”ื• ื‘โ€‘`core/` ืฆืจื™ืš ืœื™ื™ื‘ื ืžโ€‘`infra/`
ืื• ืžโ€‘`verticals/` โ€” ื”ื•ื ืœื ืฉื™ื™ืš ืœโ€‘`core/`.

## ื”ืฉื›ื‘ื•ืช

### `core/` โ€” ื”ืœื™ื‘ื” ื”ืื ืœื™ื˜ื™ืช  โœ… ื”ื•ื’ืจ ื‘-Stage 0
ืžื•ื“ืœ ื”ื ืชื•ื ื™ื ื”ืงื ื•ื ื™ ื•ื”ืžืชืžื˜ื™ืงื” ื”ื“ื˜ืจืžื™ื ื™ืกื˜ื™ืช. stdlib ื‘ืœื‘ื“, ืœืœื I/O, ืœืœื state.
- `events.py` โ€” `CanonicalEvent`
- `state.py` โ€” `EntityState`
- `ontology.py` โ€” `Entity`, `ENTITY_TYPES`
- `signals.py` โ€” ฮ”, ฯˆ, ฮพ, ฮณ, ฮบ, ฮฉ (signal math)
- `drift.py` โ€” `DriftIssue`, `drift_score`, `severity_from_score`
- `decisions.py` โ€” `DecisionItem`, `recommendation_for_issue`

ื–ื• ื”ืฉื›ื‘ื” ื”ื™ื—ื™ื“ื” ืฉื—ื™ื™ื‘ืช ืœื”ื™ื•ืช ืžื›ื•ืกื” ื‘โ€‘100% ื‘ื‘ื“ื™ืงื•ืช correctness ืืžื™ืชื™ื•ืช.
ื”ื™ื•ื: 36 ื‘ื“ื™ืงื•ืช, ื›ื•ืœืœ ื‘ื“ื™ืงืช leadโ€‘time ืื™ื ื˜ื’ืจื˜ื™ื‘ื™ืช (`tests/test_core_integration.py`).

### `verticals/` โ€” adapters ืœืื ื›ื™ื  โœ… Stage 1 (logistics)
adapter ืขื•ืฉื” ืขื‘ื•ื“ื” ืื—ืช: ืžืžืคื” ืกื›ืžื” ื’ื•ืœืžื™ืช ืฉืœ ืœืงื•ื— ืœโ€‘canonical events/metrics
ืฉโ€‘`core/` ืžื‘ื™ืŸ. **ืฉื•ื ืœื•ื’ื™ืงื” ืื ืœื™ื˜ื™ืช ื‘โ€‘adapter** โ€” ื”ื•ื ืชืจื’ื•ื ื‘ืœื‘ื“.
`logistics/` ื”ื•ื ื”โ€‘adapter ื”ืจืืฉื•ืŸ (`config.yaml` + `adapter.py`).
`team_drift_detector.py` ื”ื•ื’ืจ ืœื›ืืŸ โ€” detector, ืœื core, superseded ืข"ื™ ื”ืฆื™ื ื•ืจ ื”ื’ื ืจื™.

### `harness/` โ€” harness ืื™ืžื•ืช  โœ… Stage 2
ืžื—ื•ืœืœ ืชืจื—ื™ืฉื™ื ืžืชื•ื™ื’ื™ื ื•ืžื•ื“ื“ ืืช ื”ืžื ื•ืข ืžื•ืœ ground truth: precision, recall,
detection delay, leadโ€‘time. ืชืœื•ื™ ื‘โ€‘`core/` ื‘ืœื‘ื“. ื’ื ืฉืขืจ CI ื•ื’ื ื”ื“ืžื• ืฉืœ ื”ืžื•ืฆืจ
(`python -m harness`).

### `infra/` โ€” ืฉื›ื‘ืช ืชืฉืชื™ืช  (Stage 3, ื‘ืคืจื•ืกื•ืช)
**3a โœ…** `infra/storage/` โ€” ืื—ืกื•ืŸ: tenants, calibrations, runs (SQLite ื”ื™ื•ื,
ื”โ€‘`Database` ื‘โ€‘`db.py` ื”ื•ื ื”โ€‘seam ืœโ€‘Postgres). `infra/service.py` โ€”
`OrgStateService`, ืฉื›ื‘ืช ื”ืชื–ืžื•ืจ ืฉืžื—ื‘ืจืช `core` ืœโ€‘`storage`.
**3b โœ…** `infra/api/` โ€” shell ื“ืง ืฉืœ HTTP: `handlers.py` (ืœื•ื’ื™ืงื” ื˜ื”ื•ืจื”, ืœืœื
fastapi), `errors.py` (ืžื•ื“ืœ ืฉื’ื™ืื•ืช), `app.py` (ื—ื™ื•ื•ื˜ FastAPI). ื”ืฉืจืฉืจืช:
FastAPI app โ†’ handlers โ†’ OrgStateService โ†’ core+storage.
**3c โœ…** `infra/ingestion/` โ€” `connectors.py` (`Connector` ABC,
`InMemoryConnector`, `CSVFolderConnector`, `build_connector`) +
`scheduler.py` (`Schedule` ื ืฉืžืจ, `is_due`/`due_schedules` ื˜ื”ื•ืจื™ื,
`IngestionService`, `run_scheduler` loop ื“ืง). connector = "ืžืื™ืคื” ื”ื“ืื˜ื”",
ื”โ€‘adapter ืขื“ื™ื™ืŸ ื‘ืขืœ ืžื™ืคื•ื™ ื”ืกื›ืžื”.
**3d โœ…** `infra/deployment/` โ€” `settings.py` (`RuntimeSettings` ืžโ€‘env),
`observability.py` (logging ืžื•ื‘ื ื” JSON), `scheduler_service.py` (entry point
ืฉืœ ื”โ€‘worker). `Dockerfile` + `docker-compose.yml` ื‘ืจืžืช ื”โ€‘repo โ€” api ื•โ€‘scheduler
ื›ืฉื ื™ processes ืขืœ image ืื—ื“ ืฉื—ื•ืœืงื™ื DB ืื—ื“ ื“ืจืš `ORGSTATE_DB_PATH`.
ื ื•ืชืจ: auth/RBAC (`auth_*.py`) ื•โ€‘backend Postgres โ€” ืคืจื•ืกื•ืช ื ืคืจื“ื•ืช ื“ืจืš ื”โ€‘seam.

### `delivery/` โ€” ืคืœื˜ ืžื•ืœ ืœืงื•ื—  (Stage 4)
ื“ื•ื— ื ื™ื”ื•ืœื™, ืชื•ืจ ื”ื—ืœื˜ื•ืช, evidence views, ื“ืฉื‘ื•ืจื“ื™ื, branded report builder,
PDF export. ื”ื™ื•ื ื‘โ€‘`legacy/`: `customer_report_builder.py`,
`executive_audit_report_builder.py`, `branded_report_builder_v31.py`,
`*_dashboard*.py`, `evidence_view_builder.py`, `pdf_exporter_v28.py`.

## ื ืชื™ื‘ ื”ื ืชื•ื ื™ื (ื›ืฉื”ืžื‘ื ื” ื™ื•ืฉืœื)

```
ืžืงื•ืจ ื“ืื˜ื” ืฉืœ ืœืงื•ื—
  โ†’ verticals/<vertical>  (ืžื™ืคื•ื™ ืกื›ืžื” โ†’ CanonicalEvent)
  โ†’ core  (EntityState โ†’ signals ฮ”ฯˆฮพฮณฮบ โ†’ ฮฉ โ†’ drift_score โ†’ DecisionItem)
  โ†’ infra  (persist, schedule, serve via API)
  โ†’ delivery  (executive report, decision queue, evidence view)
```

## ื”ื—ืœื˜ื•ืช ืžื‘ื ื” ืžื•ื“ืขื•ืช

- **`infra/` ื•ืœื `platform/`** โ€” `platform` ืžืฆืœ ืขืœ ืžื•ื“ื•ืœ stdlib ื‘ืฉื ื–ื”.
- **`core/` ืœืœื ืชืœื•ื™ื•ืช** โ€” ื›ื“ื™ ืฉื”ื‘ื“ื™ืงื•ืช ื™ื”ื™ื• ืžื”ื™ืจื•ืช, ื•ืฉืื™ ืืคืฉืจ ื™ื”ื™ื”
  "ืœื”ื‘ืจื™ื—" I/O ืื• state ืœืชื•ืš ื”ืœื™ื‘ื”.
- **`legacy/` ื ืฉืืจ ืจืฅ** โ€” ืœื ืžืฉื‘ืจื™ื ื›ืœื•ื. ื›ืœ ืฉืœื‘ ืžื”ื’ืจ ืจื›ื™ื‘, ืžื—ืœื™ืฃ ืืช
  ื”โ€‘import, ื•ืžื•ื—ืง ืืช ื”ืžืงื•ืจ ืžโ€‘`legacy/` ืจืง ื›ืฉื”ื‘ื“ื™ืงื•ืช ื™ืจื•ืงื•ืช.