Content
# TNL Intelligence
Open-source developer tools for [The Neural Ledger](https://theneuralledger.com) intelligence API.
TNL Intelligence gives AI agents and quantitative research systems structured, source-linked global event intelligence. It is an evidence and research layer, not a broker, an order router, or a source of trading-grade prices.
## Packages
| Package | Purpose |
| ----------------------------- | ------------------------------------------------------------ |
| `@theneuralledger/sdk` | Typed TypeScript client for the TNL `/v1` API |
| `@theneuralledger/mcp` | Read-only MCP server over stdio or Streamable HTTP |
| `@theneuralledger/gateway` | Hosted OAuth, tenant policy, quota, and audit MCP gateway |
| `@theneuralledger/onboarding` | Developer credentials, static sample API, and explorer |
| `@theneuralledger/events` | Webhook contracts, signed delivery, and verification helpers |
| `@theneuralledger/research` | Evidence-first skills, orchestration, MCP App, and web UI |
| `@theneuralledger/adapters` | Shared Cursor and OpenAI workflow contracts and rendering |
| `@theneuralledger/connectors` | Shared n8n, Pipedream, and Zapier action/trigger contracts |
| `@theneuralledger/cli` | `tnl` CLI, watch command, local cache, and foreground daemon |
| `tnl-intelligence` | Python SDK and optional point-in-time quant research toolkit |
## Quick Start
Set a member API key in the environment:
```bash
export TNL_API_KEY="..."
```
Run the MCP server over stdio:
```bash
npx -y @theneuralledger/mcp
```
Or run its localhost Streamable HTTP endpoint:
```bash
docker compose up --build
curl http://127.0.0.1:7317/healthz
```
Use the CLI:
```bash
npx -y @theneuralledger/cli latest
npx -y @theneuralledger/cli search "Federal Reserve"
```
Use the TypeScript SDK:
```ts
import { TnlClient } from '@theneuralledger/sdk';
const client = new TnlClient({ apiKey: process.env.TNL_API_KEY! });
const page = await client.listNews({ sort: 'pipeline', pageSize: 20 });
```
Use the Python SDK:
```python
from tnl_intelligence import TnlClient
with TnlClient(api_key="...") as client:
page = client.list_news(sort="pipeline", page_size=20)
```
## Security
- API keys are never accepted as visible command-line arguments.
- MCP tools are read-only and do not place trades.
- Streamable HTTP binds to `127.0.0.1` by default.
- Local daemon events never contain the API key.
- Hosted deployments use the separate gateway, TLS ingress, OAuth validation,
tenant policy, short-lived upstream capabilities, and distributed quotas.
See [SECURITY.md](SECURITY.md) and the [build plan](docs/planning/tnl-intelligence-build-plan.md).
Research deployment boundaries and staged rollout are documented in
[Research operations](docs/research-operations.md).
## Development
```bash
npm install
npm run openapi:sync
npm run validate
```
Python development uses the project under `python/tnl_intelligence`.
## Documentation
- [Architecture](docs/architecture.md)
- [Configuration and credential handling](docs/configuration.md)
- [Hosted gateway operations](docs/gateway-operations.md)
- [Developer onboarding](docs/developer/index.md)
- [Webhook operations](docs/webhook-operations.md)
- [Foreground daemon operations](docs/daemon.md)
- [Publication runbook](docs/publishing.md)
- [Distribution and product expansion strategy](docs/distribution-and-product-expansion.md)
- [AI client adapters](docs/ai-client-adapters.md)
- [Automation connectors](docs/automation-connectors.md)
- [Quantitative research toolkit](docs/quant-research-toolkit.md)
- [Implementation plan](docs/planning/tnl-intelligence-build-plan.md)
- [Distribution tools build plan](docs/planning/tnl-distribution-tools-build-plan.md)
## License
MIT
