observeco 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- observeco-0.1.0/.codegraph/.gitignore +16 -0
- observeco-0.1.0/.codegraph/codegraph.db +0 -0
- observeco-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md +30 -0
- observeco-0.1.0/.github/workflows/ci.yml +46 -0
- observeco-0.1.0/.github/workflows/publish.yml +35 -0
- observeco-0.1.0/.gitignore +31 -0
- observeco-0.1.0/CONTRIBUTING.md +38 -0
- observeco-0.1.0/LICENSE +21 -0
- observeco-0.1.0/PKG-INFO +188 -0
- observeco-0.1.0/README.md +147 -0
- observeco-0.1.0/assets/banner.svg +88 -0
- observeco-0.1.0/assets/dashboard-fleet.png +0 -0
- observeco-0.1.0/assets/dashboard-preview.png +0 -0
- observeco-0.1.0/assets/logo.svg +31 -0
- observeco-0.1.0/assets/terminal-demo.gif +0 -0
- observeco-0.1.0/assets/terminal-demo.svg +51 -0
- observeco-0.1.0/brand/LOGO_STYLE_GUIDE.md +62 -0
- observeco-0.1.0/brand/observeco-horizontal.jpg +0 -0
- observeco-0.1.0/brand/observeco-monochrome.jpg +0 -0
- observeco-0.1.0/brand/observeco-primary.jpg +0 -0
- observeco-0.1.0/brand/observeco-white.jpg +0 -0
- observeco-0.1.0/docs/commands.md +86 -0
- observeco-0.1.0/docs/comparison.md +99 -0
- observeco-0.1.0/docs/dashboard.md +33 -0
- observeco-0.1.0/docs/installation.md +38 -0
- observeco-0.1.0/docs/launch-drafts.md +229 -0
- observeco-0.1.0/docs/pro.md +21 -0
- observeco-0.1.0/docs/quickstart.md +35 -0
- observeco-0.1.0/pyproject.toml +70 -0
- observeco-0.1.0/specs/codegraph-evaluation.md +99 -0
- observeco-0.1.0/specs/comprehensive-launch-plan.md +225 -0
- observeco-0.1.0/specs/execution-plan.md +681 -0
- observeco-0.1.0/specs/expectations-gap.md +59 -0
- observeco-0.1.0/specs/market-feedback.md +64 -0
- observeco-0.1.0/specs/marketing-plan.md +428 -0
- observeco-0.1.0/specs/unified-dashboard.md +849 -0
- observeco-0.1.0/src/observeco/__init__.py +3 -0
- observeco-0.1.0/src/observeco/__main__.py +4 -0
- observeco-0.1.0/src/observeco/auto_detect.py +91 -0
- observeco-0.1.0/src/observeco/billing.py +217 -0
- observeco-0.1.0/src/observeco/chisel/__init__.py +1 -0
- observeco-0.1.0/src/observeco/chisel/drift.py +87 -0
- observeco-0.1.0/src/observeco/chisel/trim.py +122 -0
- observeco-0.1.0/src/observeco/clawforge/__init__.py +1 -0
- observeco-0.1.0/src/observeco/clawforge/garden.py +210 -0
- observeco-0.1.0/src/observeco/clawforge/load.py +110 -0
- observeco-0.1.0/src/observeco/clawforge/profile.py +151 -0
- observeco-0.1.0/src/observeco/cli/billing_wire.py +79 -0
- observeco-0.1.0/src/observeco/cli.py +193 -0
- observeco-0.1.0/src/observeco/config.py +173 -0
- observeco-0.1.0/src/observeco/dashboard/__init__.py +1 -0
- observeco-0.1.0/src/observeco/dashboard/otel.py +109 -0
- observeco-0.1.0/src/observeco/dashboard/server.py +1107 -0
- observeco-0.1.0/src/observeco/dashboard/static/htmx.min.js +1 -0
- observeco-0.1.0/src/observeco/dashboard/templates/index.html +435 -0
- observeco-0.1.0/src/observeco/db.py +443 -0
- observeco-0.1.0/src/observeco/graph/__init__.py +1 -0
- observeco-0.1.0/src/observeco/graph/cli.py +147 -0
- observeco-0.1.0/src/observeco/graph/db.py +367 -0
- observeco-0.1.0/src/observeco/graph/extractor.py +295 -0
- observeco-0.1.0/src/observeco/graph/indexer.py +125 -0
- observeco-0.1.0/src/observeco/graph/watch.py +118 -0
- observeco-0.1.0/src/observeco/heal.py +353 -0
- observeco-0.1.0/src/observeco/mcp_server.py +336 -0
- observeco-0.1.0/src/observeco/pulse/__init__.py +1 -0
- observeco-0.1.0/src/observeco/pulse/check.py +144 -0
- observeco-0.1.0/src/observeco/pulse/circuit.py +71 -0
- observeco-0.1.0/src/observeco/snapshot.py +226 -0
- observeco-0.1.0/src/observeco/watch.py +109 -0
- observeco-0.1.0/tests/test_billing.py +51 -0
- observeco-0.1.0/tests/test_chisel.py +61 -0
- observeco-0.1.0/tests/test_clawforge.py +92 -0
- observeco-0.1.0/tests/test_cli.py +87 -0
- observeco-0.1.0/tests/test_infra.py +39 -0
- observeco-0.1.0/tests/test_pulse.py +43 -0
|
Binary file
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: Bug Report
|
|
3
|
+
about: Report a bug to help improve ObserveCo
|
|
4
|
+
title: "[Bug] "
|
|
5
|
+
labels: bug
|
|
6
|
+
assignees: ""
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
**Describe the bug**
|
|
10
|
+
A clear and concise description of what the bug is.
|
|
11
|
+
|
|
12
|
+
**To Reproduce**
|
|
13
|
+
Steps to reproduce the behavior:
|
|
14
|
+
1. Run `...`
|
|
15
|
+
2. See error
|
|
16
|
+
|
|
17
|
+
**Expected behavior**
|
|
18
|
+
What you expected to happen instead.
|
|
19
|
+
|
|
20
|
+
**Screenshots / Terminal Output**
|
|
21
|
+
If applicable, paste terminal output or screenshots.
|
|
22
|
+
|
|
23
|
+
**Environment (please complete):**
|
|
24
|
+
- OS: [e.g. macOS 15, Ubuntu 22.04, Windows 11]
|
|
25
|
+
- Python version: [e.g. 3.11, 3.12]
|
|
26
|
+
- Install method: [e.g. `pip install`, cloned repo, etc.]
|
|
27
|
+
- `observeco --version` output:
|
|
28
|
+
|
|
29
|
+
**Additional context**
|
|
30
|
+
Add any other context about the problem here.
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
branches: [main]
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
test:
|
|
11
|
+
name: "Python ${{ matrix.python-version }} on ${{ matrix.os }}"
|
|
12
|
+
runs-on: ${{ matrix.os }}
|
|
13
|
+
strategy:
|
|
14
|
+
fail-fast: false
|
|
15
|
+
matrix:
|
|
16
|
+
python-version: ["3.10", "3.11", "3.12", "3.13"]
|
|
17
|
+
os: [ubuntu-latest, macos-latest]
|
|
18
|
+
|
|
19
|
+
steps:
|
|
20
|
+
- uses: actions/checkout@v4
|
|
21
|
+
|
|
22
|
+
- name: Set up Python ${{ matrix.python-version }}
|
|
23
|
+
uses: actions/setup-python@v5
|
|
24
|
+
with:
|
|
25
|
+
python-version: ${{ matrix.python-version }}
|
|
26
|
+
cache: "pip"
|
|
27
|
+
cache-dependency-path: pyproject.toml
|
|
28
|
+
|
|
29
|
+
- name: Install dependencies
|
|
30
|
+
run: |
|
|
31
|
+
python -m pip install --upgrade pip
|
|
32
|
+
pip install -e ".[dev,dashboard]"
|
|
33
|
+
|
|
34
|
+
- name: Lint with ruff
|
|
35
|
+
run: ruff check src/observeco/
|
|
36
|
+
|
|
37
|
+
- name: Type check with mypy
|
|
38
|
+
run: mypy src/observeco/
|
|
39
|
+
|
|
40
|
+
- name: Run tests
|
|
41
|
+
run: pytest tests/ -v --tb=short --cov=observeco --cov-report=term-missing
|
|
42
|
+
|
|
43
|
+
- name: Build package
|
|
44
|
+
run: |
|
|
45
|
+
pip install build
|
|
46
|
+
python -m build --wheel --sdist .
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
name: Publish to PyPI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
tags:
|
|
6
|
+
- "v*"
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
publish:
|
|
10
|
+
name: Build and publish to PyPI
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
permissions:
|
|
13
|
+
contents: read
|
|
14
|
+
id-token: write # needed for trusted publishing
|
|
15
|
+
|
|
16
|
+
steps:
|
|
17
|
+
- uses: actions/checkout@v4
|
|
18
|
+
|
|
19
|
+
- name: Set up Python 3.12
|
|
20
|
+
uses: actions/setup-python@v5
|
|
21
|
+
with:
|
|
22
|
+
python-version: "3.12"
|
|
23
|
+
cache: "pip"
|
|
24
|
+
cache-dependency-path: pyproject.toml
|
|
25
|
+
|
|
26
|
+
- name: Install build tools
|
|
27
|
+
run: |
|
|
28
|
+
python -m pip install --upgrade pip
|
|
29
|
+
pip install build
|
|
30
|
+
|
|
31
|
+
- name: Build wheel and sdist
|
|
32
|
+
run: python -m build --wheel --sdist .
|
|
33
|
+
|
|
34
|
+
- name: Publish to PyPI
|
|
35
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*.egg-info/
|
|
5
|
+
.venv/
|
|
6
|
+
venv/
|
|
7
|
+
env/
|
|
8
|
+
|
|
9
|
+
# IDE
|
|
10
|
+
.vscode/
|
|
11
|
+
.idea/
|
|
12
|
+
*.swp
|
|
13
|
+
*.swo
|
|
14
|
+
|
|
15
|
+
# OS
|
|
16
|
+
.DS_Store
|
|
17
|
+
Thumbs.db
|
|
18
|
+
|
|
19
|
+
# Build
|
|
20
|
+
dist/
|
|
21
|
+
build/
|
|
22
|
+
*.egg
|
|
23
|
+
|
|
24
|
+
# Environment
|
|
25
|
+
.env
|
|
26
|
+
*.env.local
|
|
27
|
+
|
|
28
|
+
# Docs build
|
|
29
|
+
website/node_modules/
|
|
30
|
+
website/.docusaurus/
|
|
31
|
+
website/build/
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
## Development Setup
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
git clone https://github.com/observeco/observeco
|
|
7
|
+
cd observeco
|
|
8
|
+
python3 -m venv .venv
|
|
9
|
+
source .venv/bin/activate
|
|
10
|
+
pip install -e ".[dev]"
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Code Style
|
|
14
|
+
|
|
15
|
+
- Ruff for linting and formatting
|
|
16
|
+
- Mypy for type checking (strict mode)
|
|
17
|
+
- Pre-commit hooks: `ruff check && mypy src/`
|
|
18
|
+
|
|
19
|
+
## Testing
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
pytest # Run all tests
|
|
23
|
+
pytest -v # Verbose
|
|
24
|
+
pytest tests/test_cli.py # Single file
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Pull Requests
|
|
28
|
+
|
|
29
|
+
1. Create a feature branch from `main`
|
|
30
|
+
2. Add tests for new functionality
|
|
31
|
+
3. Ensure all tests pass
|
|
32
|
+
4. Run `ruff check src/` and `mypy src/`
|
|
33
|
+
5. Open a PR with a clear description
|
|
34
|
+
|
|
35
|
+
## Issues
|
|
36
|
+
|
|
37
|
+
- Bug reports: include Python version, OS, and reproduction steps
|
|
38
|
+
- Feature requests: describe the problem you're solving, not your proposed solution
|
observeco-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 ObserveCo (Sean Foo)
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
observeco-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: observeco
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Runtime observability for AI agent systems — pulse, circuit breaker, token compression, dashboard
|
|
5
|
+
Project-URL: Homepage, https://github.com/observeco/observeco
|
|
6
|
+
Project-URL: Documentation, https://github.com/observeco/observeco#readme
|
|
7
|
+
Project-URL: Repository, https://github.com/observeco/observeco
|
|
8
|
+
Author-email: Sean Foo <sean@observeco.com>
|
|
9
|
+
License: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
19
|
+
Classifier: Topic :: System :: Networking :: Monitoring
|
|
20
|
+
Requires-Python: >=3.10
|
|
21
|
+
Requires-Dist: fastapi>=0.110
|
|
22
|
+
Requires-Dist: httpx>=0.27
|
|
23
|
+
Requires-Dist: platformdirs>=4
|
|
24
|
+
Requires-Dist: rich>=13
|
|
25
|
+
Requires-Dist: typer>=0.9
|
|
26
|
+
Requires-Dist: uvicorn[standard]>=0.27
|
|
27
|
+
Provides-Extra: dashboard
|
|
28
|
+
Requires-Dist: jinja2>=3.1; extra == 'dashboard'
|
|
29
|
+
Requires-Dist: python-multipart>=0.0.9; extra == 'dashboard'
|
|
30
|
+
Provides-Extra: dev
|
|
31
|
+
Requires-Dist: mypy>=1.0; extra == 'dev'
|
|
32
|
+
Requires-Dist: pytest-cov>=4; extra == 'dev'
|
|
33
|
+
Requires-Dist: pytest>=7; extra == 'dev'
|
|
34
|
+
Requires-Dist: ruff>=0.3; extra == 'dev'
|
|
35
|
+
Provides-Extra: graph
|
|
36
|
+
Requires-Dist: tree-sitter-python>=0.25; extra == 'graph'
|
|
37
|
+
Requires-Dist: tree-sitter>=0.25; extra == 'graph'
|
|
38
|
+
Provides-Extra: watch
|
|
39
|
+
Requires-Dist: watchdog>=4; extra == 'watch'
|
|
40
|
+
Description-Content-Type: text/markdown
|
|
41
|
+
|
|
42
|
+
# ObserveCo
|
|
43
|
+
|
|
44
|
+
> Runtime observability for your AI agents — built for Hermes, works with anything.
|
|
45
|
+
> Know if your agents are alive, what's in their context, and when something breaks — all from a single `pip install`.
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
pip install observeco[dashboard] && observeco dashboard
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
<img src="assets/terminal-demo.svg" alt="observeco terminal demo showing pulse check and chisel trim" width="800">
|
|
52
|
+
|
|
53
|
+
<div align="center">
|
|
54
|
+
|
|
55
|
+
[](LICENSE)
|
|
56
|
+
[](pyproject.toml)
|
|
57
|
+
[](https://github.com/observeco/observeco/actions/workflows/ci.yml)
|
|
58
|
+
[](https://pypi.org/project/observeco/)
|
|
59
|
+
[](https://github.com/observeco/observeco)
|
|
60
|
+
|
|
61
|
+
</div>
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## The Dogfood Story
|
|
66
|
+
|
|
67
|
+
We run 7 autonomous agents on an M4 Mac Mini — Hermes, Kepler, Hound, Dreamer, Aleph, PA, and an orchestrator. They communicate via ACPS signals, trigger on fswatch, get scheduled via cron, and their system prompts were growing 15% week-over-week with nobody watching. So we built ObserveCo.
|
|
68
|
+
|
|
69
|
+
We also run Kepler as an OpenClaw agent — persistent, file-driven, with MEMORY.md tracking and dynamic skill loading. Its context was bloating from a different source: memory accumulation, not prompt composition. So we built ClawForge — intent-aware loading and memory hygiene, designed for OpenClaw's architecture.
|
|
70
|
+
|
|
71
|
+
Two frameworks, two optimizers, one dashboard.
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## Features
|
|
76
|
+
|
|
77
|
+
| Command | What it does |
|
|
78
|
+
|---------|-------------|
|
|
79
|
+
| `observeco pulse check` | Agent liveness — alive/dead/error per agent, zero config for Hermes users |
|
|
80
|
+
| `observeco pulse circuit` | N-failure breaker with auto-cooldown and manual reset |
|
|
81
|
+
| `observeco chisel trim` | System prompt compression with per-component token breakdown |
|
|
82
|
+
| `observeco chisel drift` | 7-day rolling token drift trend per component per agent |
|
|
83
|
+
| `observeco clawforge profile` | Context profiler for OpenClaw: MEMORY.md size, skill count, workspace bloat |
|
|
84
|
+
| `observeco clawforge load` | Intent-aware classifier — dry-run which sources would load per message |
|
|
85
|
+
| `observeco clawforge garden` | Memory hygiene — find duplicates, contradictions, stale entries |
|
|
86
|
+
| `observeco dashboard` | Local web UI: fleet health, token profiles, error timeline, memory debt score |
|
|
87
|
+
|
|
88
|
+
All data local. No cloud. No telemetry.
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
## Quick Start
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
pip install observeco
|
|
96
|
+
|
|
97
|
+
# Check your agent fleet health
|
|
98
|
+
observeco pulse check
|
|
99
|
+
|
|
100
|
+
# See circuit breaker state
|
|
101
|
+
observeco pulse circuit
|
|
102
|
+
|
|
103
|
+
# Compress a system prompt
|
|
104
|
+
echo "Your long system prompt here with tool definitions" | observeco chisel trim
|
|
105
|
+
|
|
106
|
+
# Profile an OpenClaw agent's context
|
|
107
|
+
observeco clawforge profile
|
|
108
|
+
|
|
109
|
+
# Test the intent-aware loader
|
|
110
|
+
observeco clawforge load --probe
|
|
111
|
+
|
|
112
|
+
# Launch the dashboard
|
|
113
|
+
observeco dashboard
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
## Why ObserveCo?
|
|
119
|
+
|
|
120
|
+
| Instead of... | ObserveCo gives you |
|
|
121
|
+
|---------------|-------------------|
|
|
122
|
+
| **Datadog** ($15+/host/mo, cloud-only) | `pip install`, local-first, free, understands tokens + memory debt + circuit breakers |
|
|
123
|
+
| **Grafana + Prometheus** (2-hour setup, no context concept) | 60 seconds to first health data, agent-aware dashboards |
|
|
124
|
+
| **LangSmith** (LangChain-only, $59/mo) | Framework-agnostic, open source, works offline |
|
|
125
|
+
| **Custom shell scripts** (no dashboard, no trends, no alerts) | Dashboard, drift tracking, circuit breakers, memory hygiene |
|
|
126
|
+
| **Nothing** (failing silently) | You'll know when your agents are sick, bloated, or broken |
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## Supported Frameworks
|
|
131
|
+
|
|
132
|
+
| Framework | pulse check | pulse circuit | chisel trim | chisel drift | clawforge | Dashboard |
|
|
133
|
+
|-----------|:-----------:|:-------------:|:-----------:|:------------:|:---------:|:---------:|
|
|
134
|
+
| **Hermes** | ✅ Auto | ✅ | ✅ | ✅ | ⬜ | ✅ Full |
|
|
135
|
+
| **OpenClaw** | ✅ (health endpoint) | ◐ (no native circuit) | ⬜ | ⬜ | ✅ v1 | ✅ ~85% |
|
|
136
|
+
| **Ollama** | ✅ (health endpoint) | ⬜ | ⬜ | ⬜ | ⬜ | ✅ Basic |
|
|
137
|
+
| **LangChain/LangGraph** | ◐ | ◐ | ⬜ | ⬜ | ⬜ | ✅ Basic |
|
|
138
|
+
| **CrewAI** | ◐ | ⬜ | ⬜ | ⬜ | ⬜ | ✅ Basic |
|
|
139
|
+
| **Custom/Any** | ◐ (if health endpoint) | ◐ | ◐ (stdin pipe) | ⬜ | ⬜ | ✅ Basic |
|
|
140
|
+
|
|
141
|
+
✅ = Auto-detect & works ◐ = Works if you have a health endpoint/piped input ⬜ = v2 feature
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## Architecture
|
|
146
|
+
|
|
147
|
+
```
|
|
148
|
+
pip install observeco
|
|
149
|
+
├── pulse check — agent liveness heartbeat
|
|
150
|
+
├── pulse circuit — N-failure trip → auto-block → cooldown
|
|
151
|
+
├── chisel trim — system prompt compression (Hermes — token savings)
|
|
152
|
+
├── chisel drift — token allocation diff over time (Hermes)
|
|
153
|
+
├── clawforge profile — context profiler (OpenClaw — MEMORY.md, skills, workspace)
|
|
154
|
+
├── clawforge load — intent-aware context loader (OpenClaw — ContextEngine hook)
|
|
155
|
+
├── clawforge garden — memory hygiene agent (OpenClaw — dedup, archive, flag)
|
|
156
|
+
└── observeco dashboard — local web UI, ships with library
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
- **Storage:** Local SQLite (`~/.observeco/pulse.db`) — zero setup, ships with Python
|
|
160
|
+
- **Web server:** FastAPI + htmx — no build step, no npm, ships with the CLI
|
|
161
|
+
- **CLI:** Typer — beautiful `--help`, shell completion, rich output
|
|
162
|
+
|
|
163
|
+
---
|
|
164
|
+
|
|
165
|
+
## Roadmap
|
|
166
|
+
|
|
167
|
+
- [x] `pulse check` — agent liveness
|
|
168
|
+
- [x] `pulse circuit` — circuit breaker
|
|
169
|
+
- [x] `chisel trim` — token compression
|
|
170
|
+
- [x] `chisel drift` — token diff over time
|
|
171
|
+
- [x] `clawforge profile` — context profiler
|
|
172
|
+
- [x] `clawforge load` — intent-aware classifier
|
|
173
|
+
- [x] `clawforge garden` — memory hygiene
|
|
174
|
+
- [x] Dashboard — fleet view, token profiles, error timeline
|
|
175
|
+
- [x] Stripe billing — Solo ($9/mo) + Team ($49/mo)
|
|
176
|
+
- [ ] Framework adapters for LangChain, CrewAI, AutoGen
|
|
177
|
+
- [ ] Push notifications (Pro)
|
|
178
|
+
- [ ] Multi-host fleet monitoring
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## Contributing
|
|
183
|
+
|
|
184
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md). First-time contributors welcome — look for "good first issue" labels.
|
|
185
|
+
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
Built with ❤️ for the AI agent community. MIT licensed.
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
# ObserveCo
|
|
2
|
+
|
|
3
|
+
> Runtime observability for your AI agents — built for Hermes, works with anything.
|
|
4
|
+
> Know if your agents are alive, what's in their context, and when something breaks — all from a single `pip install`.
|
|
5
|
+
|
|
6
|
+
```bash
|
|
7
|
+
pip install observeco[dashboard] && observeco dashboard
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
<img src="assets/terminal-demo.svg" alt="observeco terminal demo showing pulse check and chisel trim" width="800">
|
|
11
|
+
|
|
12
|
+
<div align="center">
|
|
13
|
+
|
|
14
|
+
[](LICENSE)
|
|
15
|
+
[](pyproject.toml)
|
|
16
|
+
[](https://github.com/observeco/observeco/actions/workflows/ci.yml)
|
|
17
|
+
[](https://pypi.org/project/observeco/)
|
|
18
|
+
[](https://github.com/observeco/observeco)
|
|
19
|
+
|
|
20
|
+
</div>
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## The Dogfood Story
|
|
25
|
+
|
|
26
|
+
We run 7 autonomous agents on an M4 Mac Mini — Hermes, Kepler, Hound, Dreamer, Aleph, PA, and an orchestrator. They communicate via ACPS signals, trigger on fswatch, get scheduled via cron, and their system prompts were growing 15% week-over-week with nobody watching. So we built ObserveCo.
|
|
27
|
+
|
|
28
|
+
We also run Kepler as an OpenClaw agent — persistent, file-driven, with MEMORY.md tracking and dynamic skill loading. Its context was bloating from a different source: memory accumulation, not prompt composition. So we built ClawForge — intent-aware loading and memory hygiene, designed for OpenClaw's architecture.
|
|
29
|
+
|
|
30
|
+
Two frameworks, two optimizers, one dashboard.
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## Features
|
|
35
|
+
|
|
36
|
+
| Command | What it does |
|
|
37
|
+
|---------|-------------|
|
|
38
|
+
| `observeco pulse check` | Agent liveness — alive/dead/error per agent, zero config for Hermes users |
|
|
39
|
+
| `observeco pulse circuit` | N-failure breaker with auto-cooldown and manual reset |
|
|
40
|
+
| `observeco chisel trim` | System prompt compression with per-component token breakdown |
|
|
41
|
+
| `observeco chisel drift` | 7-day rolling token drift trend per component per agent |
|
|
42
|
+
| `observeco clawforge profile` | Context profiler for OpenClaw: MEMORY.md size, skill count, workspace bloat |
|
|
43
|
+
| `observeco clawforge load` | Intent-aware classifier — dry-run which sources would load per message |
|
|
44
|
+
| `observeco clawforge garden` | Memory hygiene — find duplicates, contradictions, stale entries |
|
|
45
|
+
| `observeco dashboard` | Local web UI: fleet health, token profiles, error timeline, memory debt score |
|
|
46
|
+
|
|
47
|
+
All data local. No cloud. No telemetry.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## Quick Start
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
pip install observeco
|
|
55
|
+
|
|
56
|
+
# Check your agent fleet health
|
|
57
|
+
observeco pulse check
|
|
58
|
+
|
|
59
|
+
# See circuit breaker state
|
|
60
|
+
observeco pulse circuit
|
|
61
|
+
|
|
62
|
+
# Compress a system prompt
|
|
63
|
+
echo "Your long system prompt here with tool definitions" | observeco chisel trim
|
|
64
|
+
|
|
65
|
+
# Profile an OpenClaw agent's context
|
|
66
|
+
observeco clawforge profile
|
|
67
|
+
|
|
68
|
+
# Test the intent-aware loader
|
|
69
|
+
observeco clawforge load --probe
|
|
70
|
+
|
|
71
|
+
# Launch the dashboard
|
|
72
|
+
observeco dashboard
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## Why ObserveCo?
|
|
78
|
+
|
|
79
|
+
| Instead of... | ObserveCo gives you |
|
|
80
|
+
|---------------|-------------------|
|
|
81
|
+
| **Datadog** ($15+/host/mo, cloud-only) | `pip install`, local-first, free, understands tokens + memory debt + circuit breakers |
|
|
82
|
+
| **Grafana + Prometheus** (2-hour setup, no context concept) | 60 seconds to first health data, agent-aware dashboards |
|
|
83
|
+
| **LangSmith** (LangChain-only, $59/mo) | Framework-agnostic, open source, works offline |
|
|
84
|
+
| **Custom shell scripts** (no dashboard, no trends, no alerts) | Dashboard, drift tracking, circuit breakers, memory hygiene |
|
|
85
|
+
| **Nothing** (failing silently) | You'll know when your agents are sick, bloated, or broken |
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## Supported Frameworks
|
|
90
|
+
|
|
91
|
+
| Framework | pulse check | pulse circuit | chisel trim | chisel drift | clawforge | Dashboard |
|
|
92
|
+
|-----------|:-----------:|:-------------:|:-----------:|:------------:|:---------:|:---------:|
|
|
93
|
+
| **Hermes** | ✅ Auto | ✅ | ✅ | ✅ | ⬜ | ✅ Full |
|
|
94
|
+
| **OpenClaw** | ✅ (health endpoint) | ◐ (no native circuit) | ⬜ | ⬜ | ✅ v1 | ✅ ~85% |
|
|
95
|
+
| **Ollama** | ✅ (health endpoint) | ⬜ | ⬜ | ⬜ | ⬜ | ✅ Basic |
|
|
96
|
+
| **LangChain/LangGraph** | ◐ | ◐ | ⬜ | ⬜ | ⬜ | ✅ Basic |
|
|
97
|
+
| **CrewAI** | ◐ | ⬜ | ⬜ | ⬜ | ⬜ | ✅ Basic |
|
|
98
|
+
| **Custom/Any** | ◐ (if health endpoint) | ◐ | ◐ (stdin pipe) | ⬜ | ⬜ | ✅ Basic |
|
|
99
|
+
|
|
100
|
+
✅ = Auto-detect & works ◐ = Works if you have a health endpoint/piped input ⬜ = v2 feature
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
## Architecture
|
|
105
|
+
|
|
106
|
+
```
|
|
107
|
+
pip install observeco
|
|
108
|
+
├── pulse check — agent liveness heartbeat
|
|
109
|
+
├── pulse circuit — N-failure trip → auto-block → cooldown
|
|
110
|
+
├── chisel trim — system prompt compression (Hermes — token savings)
|
|
111
|
+
├── chisel drift — token allocation diff over time (Hermes)
|
|
112
|
+
├── clawforge profile — context profiler (OpenClaw — MEMORY.md, skills, workspace)
|
|
113
|
+
├── clawforge load — intent-aware context loader (OpenClaw — ContextEngine hook)
|
|
114
|
+
├── clawforge garden — memory hygiene agent (OpenClaw — dedup, archive, flag)
|
|
115
|
+
└── observeco dashboard — local web UI, ships with library
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
- **Storage:** Local SQLite (`~/.observeco/pulse.db`) — zero setup, ships with Python
|
|
119
|
+
- **Web server:** FastAPI + htmx — no build step, no npm, ships with the CLI
|
|
120
|
+
- **CLI:** Typer — beautiful `--help`, shell completion, rich output
|
|
121
|
+
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
## Roadmap
|
|
125
|
+
|
|
126
|
+
- [x] `pulse check` — agent liveness
|
|
127
|
+
- [x] `pulse circuit` — circuit breaker
|
|
128
|
+
- [x] `chisel trim` — token compression
|
|
129
|
+
- [x] `chisel drift` — token diff over time
|
|
130
|
+
- [x] `clawforge profile` — context profiler
|
|
131
|
+
- [x] `clawforge load` — intent-aware classifier
|
|
132
|
+
- [x] `clawforge garden` — memory hygiene
|
|
133
|
+
- [x] Dashboard — fleet view, token profiles, error timeline
|
|
134
|
+
- [x] Stripe billing — Solo ($9/mo) + Team ($49/mo)
|
|
135
|
+
- [ ] Framework adapters for LangChain, CrewAI, AutoGen
|
|
136
|
+
- [ ] Push notifications (Pro)
|
|
137
|
+
- [ ] Multi-host fleet monitoring
|
|
138
|
+
|
|
139
|
+
---
|
|
140
|
+
|
|
141
|
+
## Contributing
|
|
142
|
+
|
|
143
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md). First-time contributors welcome — look for "good first issue" labels.
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
Built with ❤️ for the AI agent community. MIT licensed.
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 640" width="1280" height="640">
|
|
2
|
+
<defs>
|
|
3
|
+
<linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
|
|
4
|
+
<stop offset="0%" style="stop-color:#0F172A;stop-opacity:1" />
|
|
5
|
+
<stop offset="100%" style="stop-color:#1E293B;stop-opacity:1" />
|
|
6
|
+
</linearGradient>
|
|
7
|
+
<linearGradient id="accent" x1="0%" y1="0%" x2="100%" y2="100%">
|
|
8
|
+
<stop offset="0%" style="stop-color:#0EA5E9;stop-opacity:1" />
|
|
9
|
+
<stop offset="100%" style="stop-color:#14B8A6;stop-opacity:1" />
|
|
10
|
+
</linearGradient>
|
|
11
|
+
</defs>
|
|
12
|
+
|
|
13
|
+
<!-- Background -->
|
|
14
|
+
<rect width="1280" height="640" fill="url(#bg)"/>
|
|
15
|
+
|
|
16
|
+
<!-- Decorative grid dots -->
|
|
17
|
+
<g fill="#334155" opacity="0.3">
|
|
18
|
+
<circle cx="100" cy="100" r="1"/><circle cx="200" cy="100" r="1"/>
|
|
19
|
+
<circle cx="300" cy="100" r="1"/><circle cx="400" cy="100" r="1"/>
|
|
20
|
+
<circle cx="500" cy="100" r="1"/><circle cx="600" cy="100" r="1"/>
|
|
21
|
+
<circle cx="700" cy="100" r="1"/><circle cx="800" cy="100" r="1"/>
|
|
22
|
+
<circle cx="900" cy="100" r="1"/><circle cx="1000" cy="100" r="1"/>
|
|
23
|
+
<circle cx="1100" cy="100" r="1"/><circle cx="1200" cy="100" r="1"/>
|
|
24
|
+
</g>
|
|
25
|
+
|
|
26
|
+
<!-- Logo icon -->
|
|
27
|
+
<g transform="translate(60, 50)">
|
|
28
|
+
<circle cx="32" cy="32" r="28" fill="none" stroke="url(#accent)" stroke-width="1.5" opacity="0.4"/>
|
|
29
|
+
<polyline points="4,32 14,32 18,20 22,40 26,18 30,44 34,22 38,32 42,22 46,44 50,18 54,40 58,20 60,32"
|
|
30
|
+
fill="none" stroke="url(#accent)" stroke-width="3" stroke-linecap="round"/>
|
|
31
|
+
<circle cx="18" cy="20" r="2" fill="#0EA5E9" opacity="0.7"/>
|
|
32
|
+
<circle cx="26" cy="18" r="2" fill="#14B8A6" opacity="0.7"/>
|
|
33
|
+
<circle cx="34" cy="22" r="2" fill="#06B6D4" opacity="0.7"/>
|
|
34
|
+
<circle cx="42" cy="22" r="2" fill="#0EA5E9" opacity="0.7"/>
|
|
35
|
+
<circle cx="50" cy="18" r="2" fill="#14B8A6" opacity="0.7"/>
|
|
36
|
+
</g>
|
|
37
|
+
|
|
38
|
+
<!-- Title -->
|
|
39
|
+
<text x="120" y="110" font-family="system-ui, -apple-system, sans-serif" font-size="56" font-weight="700" fill="#FFFFFF">
|
|
40
|
+
ObserveCo
|
|
41
|
+
<tspan fill="url(#accent" font-size="56">.</tspan>
|
|
42
|
+
</text>
|
|
43
|
+
|
|
44
|
+
<!-- Tagline -->
|
|
45
|
+
<text x="120" y="160" font-family="system-ui, -apple-system, sans-serif" font-size="22" fill="#94A3B8">
|
|
46
|
+
Runtime observability for your AI agents
|
|
47
|
+
</text>
|
|
48
|
+
|
|
49
|
+
<!-- Terminal mockup area -->
|
|
50
|
+
<rect x="80" y="200" width="1120" height="340" rx="12" fill="#1E293B" stroke="#334155" stroke-width="1.5"/>
|
|
51
|
+
|
|
52
|
+
<!-- Terminal window dots -->
|
|
53
|
+
<circle cx="110" cy="228" r="6" fill="#EF4444"/>
|
|
54
|
+
<circle cx="135" cy="228" r="6" fill="#EAB308"/>
|
|
55
|
+
<circle cx="160" cy="228" r="6" fill="#22C55E"/>
|
|
56
|
+
|
|
57
|
+
<!-- Terminal title -->
|
|
58
|
+
<text x="640" y="235" font-family="monospace" font-size="14" fill="#64748B" text-anchor="middle">observeco pulse check</text>
|
|
59
|
+
|
|
60
|
+
<!-- Terminal lines -->
|
|
61
|
+
<!-- Line 1: command -->
|
|
62
|
+
<text x="110" y="280" font-family="monospace" font-size="16" fill="#38BDF8">$ observeco pulse check</text>
|
|
63
|
+
|
|
64
|
+
<!-- Line 2: output - hermes-triage -->
|
|
65
|
+
<text x="130" y="310" font-family="monospace" font-size="15" fill="#4ADE80">🟢 hermes-triage</text>
|
|
66
|
+
<text x="500" y="310" font-family="monospace" font-size="15" fill="#64748B">12s ago · Tokens: 4.2K · Drift: +3%</text>
|
|
67
|
+
|
|
68
|
+
<!-- Line 3: output - pragma -->
|
|
69
|
+
<text x="130" y="340" font-family="monospace" font-size="15" fill="#4ADE80">🟢 pragma</text>
|
|
70
|
+
<text x="500" y="340" font-family="monospace" font-size="15" fill="#64748B">8s ago · Tokens: 2.1K · Drift: -1%</text>
|
|
71
|
+
|
|
72
|
+
<!-- Line 4: output - kepler -->
|
|
73
|
+
<text x="130" y="370" font-family="monospace" font-size="15" fill="#FBBF24">🟡 kepler</text>
|
|
74
|
+
<text x="500" y="370" font-family="monospace" font-size="15" fill="#64748B">3m ago · Tokens: 8.1K · Drift: +18%</text>
|
|
75
|
+
|
|
76
|
+
<!-- Line 5: output - hermes-dev -->
|
|
77
|
+
<text x="130" y="400" font-family="monospace" font-size="15" fill="#F87171">🔴 hermes-dev</text>
|
|
78
|
+
<text x="500" y="400" font-family="monospace" font-size="15" fill="#64748B">45s ago · Circuit: tripped</text>
|
|
79
|
+
|
|
80
|
+
<!-- Cursor blink -->
|
|
81
|
+
<text x="110" y="440" font-family="monospace" font-size="16" fill="#38BDF8">$</text>
|
|
82
|
+
<rect x="125" y="424" width="10" height="18" fill="#38BDF8" opacity="0.8"/>
|
|
83
|
+
|
|
84
|
+
<!-- Bottom: pip install -->
|
|
85
|
+
<rect x="80" y="560" width="1120" height="50" rx="8" fill="#0F172A" stroke="#334155" stroke-width="1"/>
|
|
86
|
+
<text x="110" y="593" font-family="monospace" font-size="18" fill="#A78BFA">$ pip install observeco[dashboard]</text>
|
|
87
|
+
<text x="600" y="593" font-family="monospace" font-size="18" fill="#22C55E">✨ Done in 12s</text>
|
|
88
|
+
</svg>
|
|
Binary file
|
|
Binary file
|