bilinc 1.0.0__tar.gz

bilinc-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atakan Elik
+
+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.

bilinc-1.0.0/PKG-INFO

@@ -0,0 +1,499 @@
+Metadata-Version: 2.4
+Name: bilinc
+Version: 1.0.0
+Summary: Verifiable State Plane for Autonomous Agents
+Author: Bilinc Team
+License-Expression: MIT
+Keywords: ai-agent-memory,context-management,belief-revision,state-plane,agm,mcp-server,verification,context-budget,neuro-symbolic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: z3-solver>=4.12.0
+Requires-Dist: networkx>=3.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == "postgres"
+Requires-Dist: pgvector>=0.2; extra == "postgres"
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == "server"
+Requires-Dist: uvicorn>=0.27; extra == "server"
+Dynamic: license-file
+
+# Bilinc
+
+**Verifiable state plane for autonomous agents**
+
+[![PyPI](https://img.shields.io/pypi/v/bilinc)](https://pypi.org/project/bilinc/)
+[![CI](https://github.com/atakanelik34/Bilinc/actions/workflows/ci.yml/badge.svg)](https://github.com/atakanelik34/Bilinc/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)
+
+*A trustworthy state layer for long-running AI agents.*
+
+Bilinc helps agents keep state that is durable, reviewable, and safer to evolve over time. It combines persistence, verification, belief revision, rollback tooling, MCP access, and operator-facing health and metrics in a single Python package.
+
+## What Bilinc Is
+
+Bilinc is a **context control plane** for autonomous agents.
+
+Most memory tools focus on storing and retrieving context. Bilinc is built for the harder problem: keeping agent state usable over time when beliefs change, contradictions appear, multiple tools touch the same memory, and operators need to understand what changed and why.
+
+In practice, that means Bilinc provides:
+
+- a `StatePlane` API for memory and state operations
+- durable storage backends
+- verification and audit-aware state handling
+- snapshot, diff, and rollback workflows
+- MCP access over stdio and authenticated HTTP
+- health and Prometheus-style metrics
+
+## The Problem Bilinc Solves
+
+Long-running agents usually break down in familiar ways:
+
+- they keep stale information too long
+- they overwrite useful context without discipline
+- they accumulate contradictions
+- they expose “memory” without persistence, rollback, auth, or observability
+
+That gap matters. A memory layer that works in a demo but cannot be trusted in a real system quickly becomes operational debt.
+
+Bilinc exists to close that gap.
+
+## Why Bilinc Is Different
+
+Bilinc is not positioned as just another memory library.
+
+It is designed as a **trustworthy state layer** for agents:
+
+- **Verify before commit**
+  State can pass through validation and verification logic instead of being blindly stored.
+- **Belief revision, not only retrieval**
+  Bilinc includes AGM-style belief revision machinery for changing or conflicting state.
+- **Durable persistence**
+  SQLite persistence is part of the normal workflow, not a side feature.
+- **Recovery primitives**
+  Snapshot, diff, and rollback exist for persistent state.
+- **Operational MCP surface**
+  HTTP MCP includes bearer auth, rate limiting, health, and metrics.
+- **Operator visibility**
+  Bilinc exposes deployment signals through `/health` and `/metrics`.
+
+## Core Capabilities
+
+- **StatePlane core**
+  Unified API for commit, recall, forget, snapshot, diff, rollback, and component initialization.
+- **Persistent storage**
+  SQLite support today, PostgreSQL backend included and CI-validated.
+- **Verification and audit**
+  Z3-backed verification and audit-aware state reconstruction.
+- **Belief revision**
+  AGM-style revision workflows for conflicting or changing beliefs.
+- **Knowledge graph**
+  Semantic memory can be projected into a graph for traversal and contradiction analysis.
+- **MCP server**
+  12 MCP tools for memory and state operations.
+- **HTTP deployment surface**
+  Authenticated transport with rate limiting, health, and metrics.
+- **Observability**
+  In-process metrics plus Prometheus-compatible export.
+
+## Support and Maturity Matrix
+
+| Surface | Status | Notes |
+|---|---|---|
+| Core `StatePlane` API | Production-capable | Main package surface, covered by tests |
+| SQLite persistence | Production-capable | Persistent CLI and backend support |
+| MCP stdio transport | Supported | Trusted local process boundary, no request-level auth |
+| MCP HTTP transport | Production-capable | Bearer auth, rate limiting, health, metrics |
+| Snapshot / diff / rollback | Supported on persistent backends | Intended for durable state workflows |
+| `/health` and `/metrics` | Production-capable | Operator-facing HTTP endpoints |
+| Knowledge graph | Supported | Included in package and docs |
+| AGM belief revision | Supported | Included in package and docs |
+| PostgreSQL backend | CI-validated support | Backend integration job exists in CI |
+| LangGraph adapter | Not currently a supported public surface | Do not treat as maintained product surface |
+| Hosted service / multi-tenant platform | Planned | Not part of this repository today |
+
+## Architecture Overview
+
+Bilinc is organized as a layered agent-state system:
+
+1. **Core state layer**
+   `StatePlane` coordinates commits, recall, forgetting, rollback, and component initialization.
+2. **Persistence layer**
+   SQLite and PostgreSQL backends provide durable storage.
+3. **Verification and audit**
+   Verification and audit trail logic support correctness and replayable state history.
+4. **Belief management**
+   AGM-style revision supports controlled state updates under conflict.
+5. **Knowledge graph**
+   Semantic memory can be represented structurally and queried.
+6. **Transport layer**
+   MCP is exposed through stdio and HTTP.
+7. **Operations layer**
+   Health and metrics support deployment and monitoring.
+
+## Install
+
+Basic install:
+
+```bash
+pip install bilinc
+```
+
+Development install:
+
+```bash
+pip install -e '.[dev]'
+```
+
+PostgreSQL extras:
+
+```bash
+pip install -e '.[dev,postgres]'
+```
+
+Server-oriented extras:
+
+```bash
+pip install -e '.[server]'
+```
+
+Bilinc supports **Python 3.10+**.
+
+## Quick Start
+
+### Python API
+
+```python
+from bilinc import StatePlane
+
+plane = StatePlane()
+plane.init()
+
+result = plane.commit_sync(
+    key="user.pref.editor",
+    value={"name": "cursor", "theme": "dark"},
+    memory_type="semantic",
+    importance=0.8,
+)
+
+print(result.success)
+print(len(plane.recall_all_sync()))
+```
+
+### With Durable Storage
+
+```python
+from bilinc import StatePlane
+from bilinc.storage.sqlite import SQLiteBackend
+
+backend = SQLiteBackend("./bilinc.db")
+plane = StatePlane(backend=backend)
+plane.init()
+
+plane.commit_sync(
+    key="team.policy",
+    value={"deploy_window": "weekday"},
+    memory_type="semantic",
+)
+
+entry = plane.working_memory.get("team.policy")
+print(entry.value)
+```
+
+## Persistent CLI Usage
+
+Bilinc ships with a CLI.
+
+### Ephemeral mode
+
+Without `--db`, the CLI runs in in-memory mode:
+
+```bash
+bilinc status
+```
+
+This mode is useful for quick inspection and local testing, but it is **not persistent across separate CLI invocations**.
+
+### SQLite-backed persistent mode
+
+```bash
+bilinc --db ./bilinc.db commit --key team.owner --value alice
+bilinc --db ./bilinc.db recall --key team.owner
+bilinc --db ./bilinc.db forget --key team.owner
+```
+
+You can also provide the backend through an environment variable:
+
+```bash
+export BILINC_DB_URL=./bilinc.db
+bilinc commit --key app.mode --value production
+bilinc recall --key app.mode
+```
+
+## MCP Usage
+
+Bilinc exposes an MCP surface for agent runtimes and tool ecosystems.
+
+### Stdio transport
+
+Use stdio when Bilinc runs as a trusted local process behind an MCP client.
+
+```python
+import asyncio
+from bilinc import StatePlane
+from bilinc.mcp_server.server_v2 import create_mcp_server_v2
+from mcp.server.stdio import stdio_server
+
+plane = StatePlane()
+plane.init_agm()
+plane.init_knowledge_graph()
+
+server = create_mcp_server_v2(plane)
+
+async def main():
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+asyncio.run(main())
+```
+
+**Security note:** stdio is a **trusted local process boundary**. It is intentionally **unauthenticated at the request level**.
+
+### HTTP transport
+
+Use HTTP for production-facing deployments.
+
+```python
+from bilinc import StatePlane
+from bilinc.mcp_server.server_v2 import create_mcp_http_app
+
+plane = StatePlane()
+plane.init_agm()
+plane.init_knowledge_graph()
+
+app = create_mcp_http_app(
+    plane=plane,
+    auth_token="replace-me",
+    route_prefix="/mcp",
+)
+```
+
+Run it with your ASGI server:
+
+```bash
+uvicorn yourmodule:app --host 0.0.0.0 --port 8000
+```
+
+HTTP behavior:
+
+- `Authorization: Bearer <token>` is required by default
+- missing token: `401`
+- invalid token: `401`
+- rate-limited client: `429`
+
+Available MCP tools:
+
+- `commit_mem`
+- `recall`
+- `forget`
+- `revise`
+- `status`
+- `verify`
+- `consolidate`
+- `snapshot`
+- `diff`
+- `rollback`
+- `query_graph`
+- `contradictions`
+
+## Security Model
+
+Bilinc has two deliberate trust boundaries.
+
+### Stdio
+
+- intended for trusted local process use
+- no request-level auth
+- appropriate when the MCP client and Bilinc run in the same trust domain
+
+### HTTP
+
+- intended as the production-facing transport
+- bearer token auth enforced by default
+- rate limiting enforced
+- health and metrics available through the same deployment surface
+
+Other security-relevant behavior:
+
+- input validation for keys and values
+- resource limits for memory and graph growth
+- audit support when enabled
+- constant-time token comparison for HTTP auth
+
+## Observability, Health, and Metrics
+
+Bilinc includes a real operator surface.
+
+### Health
+
+- `GET /health`
+- reports both `liveness` and `readiness`
+- uses explicit states:
+  - `healthy`
+  - `degraded`
+  - `failed`
+
+### Metrics
+
+- `GET /metrics`
+- Prometheus-compatible
+- `bilinc_` metric prefix
+
+Examples of tracked areas:
+
+- commit / recall / forget operation totals and latencies
+- snapshot / diff / rollback totals and latencies
+- auth failures
+- rate limit hits
+- backend errors
+- readiness/liveness gauges
+
+In-process observability is also available through the Python API.
+
+## Storage Backends
+
+### SQLite
+
+Recommended for:
+
+- local durable usage
+- embedded deployments
+- single-node setups
+- controlled production environments
+
+What exists today:
+
+- persistent CLI support
+- schema version tracking
+- integration coverage
+- rollback, snapshot, and diff support for durable state flows
+
+### PostgreSQL
+
+Recommended for:
+
+- teams that want a database-backed deployment path
+- environments where SQLite is not the right operational fit
+
+What exists today:
+
+- backend implementation in the repo
+- contract-level integration tests
+- CI validation with a PostgreSQL service job
+
+Practical note:
+
+PostgreSQL support is real and tested, but it is still a narrower path than the SQLite experience and should be treated with normal production caution.
+
+## Testing, CI, and Validation
+
+Bilinc’s repository includes:
+
+- Python test matrix
+- SQLite persistence coverage
+- PostgreSQL integration coverage in CI
+- package build validation
+- wheel and sdist installation validation
+- CLI persistence smoke checks in CI
+- HTTP auth/rate-limit coverage
+- observability coverage
+
+If you are evaluating Bilinc seriously, the CI pipeline is part of the product contract.
+
+## Documentation Map
+
+- `docs/mcp-server.md`
+  MCP surface, transport notes, and tool reference
+- `docs/security.md`
+  auth, validation, limits, and deployment trust model
+- `docs/observability.md`
+  health model, readiness/liveness, and metrics
+- `docs/runbook.md`
+  operator guidance and deployment notes
+- `docs/release.md`
+  release and publish checklist
+- `CHANGELOG.md`
+  shipped changes and release history
+
+## Development and Local Setup
+
+Clone the repo and install development dependencies:
+
+```bash
+git clone git@github.com:atakanelik34/Bilinc.git
+cd Bilinc
+python -m pip install -e '.[dev]'
+```
+
+Run the full test suite:
+
+```bash
+PYTHONPATH=src pytest -q tests/
+```
+
+Build distributable artifacts:
+
+```bash
+python -m build
+```
+
+Run a local persistence smoke:
+
+```bash
+bilinc --db ./tmp.db commit --key smoke_key --value hello
+bilinc --db ./tmp.db recall --key smoke_key
+```
+
+Run PostgreSQL integration tests locally if you have a database ready:
+
+```bash
+export BILINC_TEST_POSTGRES_DSN=postgresql://postgres:postgres@127.0.0.1:5432/bilinc_test
+PYTHONPATH=src pytest -q tests/test_postgres_integration.py
+```
+
+## Roadmap
+
+Near-term priorities:
+
+- keep the shipped surface stable
+- continue validating PostgreSQL deployments
+- improve official integrations selectively
+- tighten operator and release discipline further where needed
+
+Possible future work:
+
+- broader supported integrations
+- hosted deployment model
+- richer operator tooling
+- stronger enterprise deployment paths
+
+## License
+
+[MIT](LICENSE)